1. Using Oracle Intelligent Track and Trace
  2. Unidirectional Reference Keys For Document Cross-References

Unidirectional Reference Keys For Document Cross-References

As a founder, in a document metadata, you can now define unidirectional references to create one-to-one or one-to-many correlations between different transaction documents across multiple business flows.

Limitations of Bi-directional Reference Model

Currently, all internal references between transaction documents are defined using a document ledgerKey. If the ledgerKey is not known, then bi-directional references are defined by using the references field, an array of strings that holds reference keys.

Bi-directional Reference Model - Metadata Template Structure

In the following sample metadata Test document, the references field at line number 29 to line number 31 defines cross-references to the sample document A and document B.

1 {
2     "documentTypeId": "test",
3     "documentVariantId": "default",
4     "ledgerKey": "Shipping:Test doc",
5     "documentNumber": "Test doc",
6     "originalDocumentRef": {
7         "location": {
8             "bucket": "requests_xyz_test",
9             "object": "6_8_46072df1-f9d2-4a87-a00f-bc9d52060358/document"
10        },
11        "documentHash": "f3ef1009f7dbc45ee9b40d446b3290d85b299735477a0cc753125196ea26ba3c25c15d232972fc3a60973c22ce4372d10f2a81e9b86aad35e901e0026ac78cdb"
12    },
13    "requestBodyRef": {
14        "location": {
15            "bucket": "requests_xyz_test",
16            "object": "6_8_46072df1-f9d2-4a87-a00f-bc9d52060358/document"
17        },
18        "documentHash": "f3ef1009f7dbc45ee9b40d446b3290d85b299735477a0cc753125196ea26ba3c25c15d232972fc3a60973c22ce4372d10f2a81e9b86aad35e901e0026ac78cdb"
19    },
20    "attachmentsRefs": [],
21    "receivedTimestamp": 1682579505251,
22    "documentTimestamp": 1682579505251,
23    "submitter": {
24        "tradingPartnerId": "xyz_test"
25    },
26    "receiver": {
27        "tradingPartnerId": "xyz_test"
28    },
29    "references": [
30        "A",
31        "B"
32    ],
33    "transactionValue": {
34        "currencyCode": "USD",
35        "amount": 0
36    },
37    "documentData": {}
38}

In the following sample metadata, document B defines a cross-reference to sample document C and also creates a recursive cross-reference back to itself as shown line number 30.

1 {
2     "documentTypeId": "test",
3     "documentVariantId": "default",
4     "ledgerKey": "Shipping:Test doc B",
5     "documentNumber": "Test doc B",
6     "originalDocumentRef": {
7         "location": {
8             "bucket": "requests_xyz_test",
9             "object": "6_8_cd9e9d30-d440-4471-8fbf-13c47064c40a/document"
10        },
11        "documentHash": "afd9c9a32c16c87decf1ab39393fa0353021c48576c18c5285be5215092ff9c43c2ff02818fa822344913cf8b71b80e74fcfc1db4e47652ca053084dd4d4c3ad"
12    },
13    "requestBodyRef": {
14        "location": {
15            "bucket": "requests_xyz_test",
16            "object": "6_8_cd9e9d30-d440-4471-8fbf-13c47064c40a/document"
17        },
18        "documentHash": "afd9c9a32c16c87decf1ab39393fa0353021c48576c18c5285be5215092ff9c43c2ff02818fa822344913cf8b71b80e74fcfc1db4e47652ca053084dd4d4c3ad"
19    },
20    "attachmentsRefs": [],
21    "receivedTimestamp": 1682579594052,
22    "documentTimestamp": 1682579594052,
23    "submitter": {
24        "tradingPartnerId": "xyz_test"
25    },
26    "receiver": {
27        "tradingPartnerId": "xyz_test"
28    },
29    "references": [
30        "B",
31        "C"
32    ],
33    "transactionValue": {
34        "currencyCode": "USD",
35        "amount": 0           
36    },                        
37    "documentData": {}        
38}

For large number of documents ingested into Oracle Intelligent Track and Trace, bi-directional correlations adds higher complexity due to recursive correlations. For better flexibility, you can now add unidirectional cross-references that enables you to define one-way correlations between transaction documents.

Unidirectional Reference Model

Unidirectional reference model extends fine-grained correlations between documents, it provides higher flexibility to define internal cross-references with the following benefits.
  • One-way reference to address the bi-directional recursion limitation.
  • Simplified metadata template definition for creating internal references. For example, the usage of referenceKeys instead of references field to define correlations.
  • No dependency on the document/ledger keys to define correlations.

To define unidirectional references, use the following reference key definitions:

  • referenceKeys: An array of strings that contains the reference keys that other documents can use to reference the document.
  • documentCrossRefs: The documentCrossRefs object definition uses the following two modes:
    • ledgerKey: The primary key of the document to be referenced.
    • referenceKey: Reference Key defined in another document to reference.

Sample metadata structure with unidirectional reference using referenceKey field

In this sample metadata document, line number 8 shows the documentCrossRef object definition having referenceKey field to create unidirectional reference.

1 {{#metadataDocument}}
2     {{md:documentNumber document.InvoiceNumber}}
3     {{md:ledgerKey (concat "invoice:" document.InvoiceNumber)}}
4     {{md:documentTimestamp (toTimestamp (concat document.InvoiceDate "T00:00:00Z"))}}
5     {{md:transactionValue  currencyCode=document.CurrencyCode amount=document.Amount}}
6     {{md:receiver  document.Customer by="name"}}
7     {{md:documentData "Customer" document.Customer}}
8     {{md:documentCrossRef referenceKey = (concat "LOTNUMBER:" lot.LotNumber)}}
9            
10	...
11{{/metadataDocument}}

Sample metadata structure with unidirectional references using referenceKeys field.

In this sample metadata document, line number 5 shows the referenceKey definition that other documents can use to reference this document.
## Document to be referenced from another document

1 {{#metadataDocument}}
2     {{md:documentNumber (concat "QA-" document.Id)}}
3     {{md:ledgerKey (concat "QA-" document.Id )}}
4     {{!-- Reference Keys --}}
5     {{md:documentCrossRef referenceKey = (concat "woodmove:" document.Centro ":" (split document.DataFimLote delimiter="T" index=0))}}
6     {{md:referenceKey (concat "LOTNUMBER:" LotNumber)}}
7 	...
8{{/metadataDocument}}
Note: All bi-directional references using the references field will be removed and replaced by the unidirectional references that are defined using the referencesKeys and documentCrossRef fields.

Usage Examples

For practical understanding and implementation of unidirectional correlations, let us consider transaction document QA and transaction document CI as two sample documents in a same business flow.

  1. In the sample metadata of the QA document, line number 35 shows the reference key definition of a sample document QA-020. This reference key is used by the CI document to create unidirectional cross-reference.
    
1 {
2     "documentTypeId": "QA",
3     "documentVariantId": "default",
4     "ledgerKey": "QA-120457611717-v1",
5     "documentNumber": "QA-120457611717",
6     "originalDocumentRef": {
7         "location": {
8             "bucket": "requests_test01",
9             "object": "61_63_bed15e8a-061b-4231-8feb-d9b72208e3c5/document"
10        },
11        "documentHash": "3183f0382ede82b0b64d44202d5501ea692f8f208aded107adaa7ea764824f33b4a35f82a4d308a4c65b16d5dbd4d0f2ec904672bfb457a667d868103395ee40"
12    },
13    "requestBodyRef": {
14        "location": {
15            "bucket": "requests_test01",
16            "object": "61_63_bed15e8a-061b-4231-8feb-d9b72208e3c5/document"
17        },
18        "documentHash": "3183f0382ede82b0b64d44202d5501ea692f8f208aded107adaa7ea764824f33b4a35f82a4d308a4c65b16d5dbd4d0f2ec904672bfb457a667d868103395ee40"
19    },
20    "attachmentsRefs": [],
21    "receivedTimestamp": 1684256302360,
22    "documentTimestamp": 1656719643000,
23    "submitter": {
24        "tradingPartnerId": "test01"
25    },
26    "receiver": {
27        "tradingPartnerId": "test01"
28    },
29    "documentCrossRefs": [
30        {
31            "referenceKey": "WM-011"
32        }
33    ],
34    {{!-- Reference Keys --}}
35    "referenceKeys": [
36        "QA-020"
37    ],
38    
39	...
40	
41    }
42}
  2. In this sample metadata of the CI document, line number 29 to line number 39 shows a unidirectional references defined for documents QA-001, QA-020, and QA-032.
    
!-- referenceKey field in documentCrossRefs object definition
1 {
2     "documentTypeId": "CI",
3     "documentVariantId": "default",
4     "ledgerKey": "invoice:INV-383834405697",
5     "documentNumber": "INV-383834405697",
6     "originalDocumentRef": {
7         "location": {
8             "bucket": "requests_test01",
9             "object": "61_64_b22ee1f7-df48-4976-826b-e213d92be3ca/document"
10        },
11        "documentHash": "7e3afd69450679758f7fef300418b1cf8e737a0136a707c45b3d3296ba90635becfb64ef740d6fbdc7b7370e5f5324c17bd9303f85925ba7bc8b31517807a0ee"
12    },
13    "requestBodyRef": {
14        "location": {
15            "bucket": "requests_test01",
16            "object": "61_64_b22ee1f7-df48-4976-826b-e213d92be3ca/document"
17        },
18        "documentHash": "7e3afd69450679758f7fef300418b1cf8e737a0136a707c45b3d3296ba90635becfb64ef740d6fbdc7b7370e5f5324c17bd9303f85925ba7bc8b31517807a0ee"
19    },
20    "attachmentsRefs": [],
21    "receivedTimestamp": 1684256587845,
22    "documentTimestamp": 1656979200000,
23    "submitter": {
24        "tradingPartnerId": "test01"
25    },
26    "receiver": {
27        "tradingPartnerId": "25"
28    },
29    "documentCrossRefs": [
30        {
31            "referenceKey": "QA-001"
32        },
33        {
34            "referenceKey": "QA-020"
35        },
36        {
37            "referenceKey": "QA-032"
38        }      
39    
40    ],
41	
42	...
43	
44    }
45}

In this case, the cross-reference defined in line number 34 forms a direct reference to the sample document QA-020.