Supply Chain Partner Relationships
Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019
Multiple companies in the Supply Chain Management (SCM) industry are frequently interacting with each other, but there has traditionally been no efficient method of seamlessly connecting these organizations with each other as business partners. Individual organizations have different account management processes and architecture. The objective of the Supply Chain Partner Relationships feature is to connect this ecosystem and be the digital backbone of the global SCM industry. This functionality is the beginning of a process that will allow the network members to own these relationships, facilitating the process of sharing visibility to shipment data and trade objects. Business partners can search for each other and establish a partnership. The feature can be used through the UI or through the Business Partners API and requires organization admin authority.
Basic functions include:
- An organization can search and invite the companies that are also part of the TradeLens platform to become business partners.
- An organization has the option of being “searchable” or not.
- An organization has the option to either accept or reject the partnership requests.
- An organization can refer to a partner using a party identifier, either user specified, or system generated.
Once a business partnership has been established, the party identifier can be used to give the party access to a trade object, like a consignment or transport equipment. Either a user specified party identifier or the system generated party identifier can be used.
Example Scenario: Carriers will usually be searchable and might have auto accept set for incoming business partner requests. A transport service buyer (shipper) will search for a transport service provider (carrier) and send the partner request. The carrier will auto accept the request and add party identifiers for the business partner relationship for all of the customer owned codes, or customer identification codes, that are used within the carrier's systems to identify the transport service buyer (shipper). Then the carrier will create the consignment (if it does not already exist) and add the transport service buyer to the consignment using their party identifier from the business partner relationship.
The management and operation of the feature is administered in two places: Organization Management and Business Partners
When an organization is onboarded to the TradeLens platform, the onboarding team will include optional information about an organization, such as address, city, country, state, and postal code.
Within the organization management section, an organization can select the option to be searchable and this will allow other organizations to easily find business partners through search. An organization can also choose whether to auto approve (accept) incoming business partner requests. The default for searchable and auto approve is true. Organization Management can be accessed through the UI or the APIs.
The organization management section can be found in the UI by clicking on Management within the Account drop-down. As shown below, the organization can select to be searchable and to automatically accept business partner requests.
The organization management APIs can be found in the Business Partners API drop-down in Swagger. See the API Documentation section for a link to the TradeLens APIs. The APIs are:
- GET .../profile/organization - Returns the organization's Business Partner profile
- PATCH .../profile/organization - Updates the organization's Business Partner profile
- GET .../organizations - List all searchable organizations in TradeLens Platform
In the above image from the UI, if we want to change the organization so that it auto accepts incoming business partner requests, we could do this from the UI, or through the PATCH .../profile/organization API.
The business partners function can be accessed through the UI or the APIs. A typical business partner scenario will consist of:
- Search for an organization by name.
- Select the organization, add a reference (or multiple references) for the receiving partner (optional at this step and can be done later if desired), and send the business partner request.
- Wait for a response from the receiving partner.
- Once the receiving partner approves the request, both organizations are in the business partner relationship. The receiving partner can add a reference (or multiple references) for the sending partner.
Note: When a new organization is onboarded, it should be available for business partners within about 5 minutes.
The business partners section can be found in the UI by clicking on Management within the Account drop-down.
The business partner APIs can be found in the Business Partners API drop-down in Swagger. See the API Documentation section for a link to the TradeLens APIs. The APIs are:
- GET .../partners - List the business partners and requests for the current organization
- POST .../partners - Send business partner requests to a list of organizations
- PATCH .../partners - Change the status of multiple business partner requests
States of partnership
There are five allowed states for a business partnership:
- Requested - sender will see this status until recipient takes action, state can be specified on API by sender.
- Pending - recipient will see this status for requests that have been sent to recipient but not acted upon, state can not be specified on API.
- Accepted - sender and recipient will see this status for requests that have been accepted by the recipient, state can be specified on API by recipient.
- Denied - sender and recipient will see this status for requests that have been denied by the recipient, state can be specified on API by recipient.
- Deleted - sender and recipient will see this status for partnerships that have been deleted by either party, state can be specified on API by either sender or recipient.
The table below shows possible states of a partnership between orgA and orgB.
|Action||Status in orgA||Status in orgB|
|orgA sends request to orgB||requested||pending|
|orgB approves orgA's request||accepted||accepted|
|orgB denies orgA's request||denied||denied|
|either org deletes the relationship||deleted||deleted|
Adding business partner to consignment or transport equipment
Once a business partner relationship is complete, the party identifier that was used for the organization (or the system generated party identifier) can be specified as the partyRef on the partyAdded APIs POST .../consignments/partyAdded - Consignment visibility added (E001) and POST .../transportEquipment/partyAdded - Transport equipment visibility added (E550). We will show this step near the end of the example below.
In this example we will have two organizations. Organization1 will be a transport service buyer (shipper) and organization2 will be a transport service provider (ocean carrier). The shipper will search for an ocean carrier, request a partnership and add a party identifier for the carrier. The carrier will accept the request and add a party identifier for the shipper. The carrier will use the party identifier that they specified for the shipper to add the shipper to a consignment.
As discussed in the Organizational Management section above, the ocean carrier has set the option to be searchable. The shipper searches for the carrier in the Business Partners section of the UI, or by using the GET .../organizations - List all searchable organizations in TradeLens Platform API.
The shipper can fill in a name and party identifier for the carrier. This can be a customer owned code or an existing customer identification code, that the shipper uses within their existing systems to identify the carrier. Note that specifying a user defined party identifier is optional and it can be done later or the system generated party identifier can be used. When we are done editing a party identifier line, we click the plus (+) sign and then click "Save & Send" to save the party identifier information and send the request to the carrier.
The same function using the POST .../partners API is shown below. Notice that the code parameter is the party identifier that can be used as the partyRef on the partyAdded APIs to add the party to a trade object (consignment or transport equipment).
In our case, the carrier has set the option within organizational management to auto approve, so the business partnership request from the shipper is established. If the carrier did not have auto approve set, then we would see pending requests for the carrier within the business partner UI and we could click Accept. The corresponding API is PATCH .../partners and as the carrier, we would set the status as "accepted".
The carrier can add a party identifier for the shipper, and this party identifier can then be used as the partyRef for the partyAdded API to add the shipper to a consignment. Notice in the second image below, that there is also a system generated party identifier and it can be used as the partyRef for the partyAdded API. We find the shipper in the active business partners section and click edit to add one or more party identifiers.
If the carrier had autoApprove set to false, they can manually accept a new request and add a party identifier at the same time using the PATCH .../partners API; this scenario is shown below. Or they could approve the request using the PATCH API and add party identifier(s) later (also using the PATCH API with the reference id of the partnership) if desired. Notice that the code parameter is the party identifier that can be used as the partyRef on the partyAdded APIs to add the party to a trade object (consignment or transport equipment).
Now we will show how the party identifier can be used to add the party to a consignment (or transport equipment). In our example, we will assume that the carrier already has a consignment created, so we will just add the shipper to the existing consignment, using the party identifier that the carrier specified for the business partnership. We use the POST .../consignments/partyAdded - Consignment visibility added (E001) API to add the shipper by partyRef.
From the shipper, we can now see the consignment that the carrier created, and we see that the shipper has been added with the role of transport service buyer.
Also notice the Created By filter on the UI. This additional search option will contain established business partnerships if they have these specific roles (where the role reflects how the organization was onboarded): freight forwarder, 3PL, 4PL, ocean carrier, drayage, truck, rail, and barge.