Skip to main content

Integrations

This article is for all integrations!

This Integrations instruction is for all Jakamo companies using Jakamo via API.

Any internal systems such as ERP, PLM, MES, PowerBI, Qlikview, and many others can be easily integrated with Jakamo. By integrating your internal software with Jakamo, you can automate your core supply chain processes and focus on more value-added activities.

1. Overview​

If your company has at least one integration in use towards Jakamo, company admin users will have an Integrations settings page available in Jakamo. The Integrations setting page is a place for users with company admin rights to view and manage which of their users and business partners are in use via integrations. This setting page is for company admin users to create a new mapping for new users or business partners or delete old or incorrect mappings.

What is mapping?

Mapping means data alignment between two systems. In Jakamo, mapping is data alignment between integrated systems, e.g. your ERP system and Jakamo. Mappings in Jakamo have aligned information of users and business partners between systems. This means your system's users and business partners align to match user accounts and business partners' accounts in Jakamo.

Setting page to manage your integration's settings in Jakamo can be found from the upper-left hidden menu under the Integrations. The Integrations settings page lists all the integrations your company has available. Integration settings contain user and company mappings, and authentication settings. All settings are specific to the integration, so each integration must be configure separately. On the Integrations settings page, it is possible to add new or delete existing mappings, or update integration credentials or manage OAuth2.0 applications.

The information available for the integration:

  • Name: This is the name of your integration. You can see which type of integration it is from the blue tag and the integration's name.
  • User strings: Here are listed all the users that are in use with that integration.
  • Company strings: Here are listed all the business partners that are in use with that integration.
  • Integration credentials: Here you can modify your integration credentials. Only the person responsible for the integration and connection to Jakamo should update the credentials!
  • OAuth2 App ID: Here you can register new OAuth2.0 application and manage existing ones.

2. Basic principles of user and company mappings​

note

Learn these few basic principles of integration settings before starting to update your integration settings.

  • Administration: Only company admin users can access and manage company's integration settings in Jakamo.
  • Integration-spesific settings: User and company mappings are integration-specific. Each integration has to be configured separately, for example each integration will have its own user and company mappings, and authentication. But, you can use the same mapping strings for users or business partners (for example vendor number) in different integrations.
  • Authentication: It is recommended to use OAuth2.0 as an authentication mehthod. But, if you still use basic authentication, create unique and different integration credentials for each integration you have in use. It will cause an error if you use the same credentials with multiple integrations.
  • Mapping management: You cannot modify existing mapping, you can only add new or delete existing one. If you want to update the mapping, create a new mapping and delete the old one.
  • Mapping definition: The mapping strings used are entirely up to your definition. You can define them idependently and you do not need to agree them with Jakamo, or any other partner.

3. Company mappings​

Jakamo needs to know with which companies you have relation in Jakamo you want to use also Jakamo integration. Mapping between your system identifier and Jakamo partner company is needed so that Jakamo can do the routing of the new item to the correct partner company in Jakamo.

Map your partner company in Jakamo Integrations settings page. Find all the existing partner company mappings listed under the Company strings.

3.1 Add new partner company​

If you need to add a new partner company, for example, for your supplier or customer to be automatized via integration, you can add new partner mapping from ADD COMPANY under the Company strings. Fill corect Company identifier and map it to the correct Jakamo company:

  • Add your Company identifier: Add identifier you have in your internal system to your partner, e.g. supplier number or customer number. Company identifier is typically e.g. vendor or customer number your company has in your ERP system for that partner. If you have existing mappings, follow the same structure with new ones.
  • Select Jakamo company: Select the company from the dropdown list of your Jakamo partners you are creating a mapping for. Jakamo company is a dropdown list of all the companies you have a relationship with in Jakamo.

After saving the new company mapping from the OK, you can share information with this partner via integration.

3.2 Company mapping restrictions​

You can create multiple different company mappings for the same Jakamo partner. For example, if you have several different vendor numbers you want to connect with one supplier account in Jakamo, you can create as many company mappings as you have vendor numbers in your system for that one supplier.

Example ✅: You can set different identifiers to refer one business partner in Jakamo. In this example, there are different company identifiers set to parter company Sorva Steeling:

One the other hand, you can not create mappings by using the same company identifier for two or more different Jakamo partners.

Example ❌: You can not set the same identifier to refer multiple different business partners in Jakamo. In this example, two differet partner companies, Harjun Harjateräs Oy and Sorva Steeling have identical company identifiera (12345) defined. This situation will cause error:

3.3 Delete partner company​

You can delete company mapping simply by using the trashcan icon. This deletion will only remove the integration connection with that company, so only the ability to data transfer via integration is disconnected. This will not disconnect the relationship with the deleted company.

If you want to also disconnect the relationship in Jakamo with that company, visit the partner's Jakamo company profile and disconnect the relationship there. A comprehensive guide about disconnecting the relationship can be found from Network instructions.

3.4 Mappings in purchase order integration (buyer customer party tags)​

info

The following instructions are for companies using PO integration and Jakamo to send orders to supplier companies and receive order confirmations from suppliers. Company mapping in purchase order integration is following the rules of basic company mapping.

Voluntarily, there is a possibility to create buyer customer party tags. Buyer customer party tags or tags can be defined for your company, for example, to separate your company units or sites in case your company uses the same Jakamo account with multiple sites. Defined tags will be automatically created for a new item which is shared via integration from that site. Read more about how to utilize tags in Jakamo.

Start creating company mapping normally, and create a new mapping by defining identifier related to your company, and connect it with your company account in Jakamo. Define tag or tags you want to automatically create for every new item created via that integration.

Example: Separate your own business units or locations with buyer customer party tags. In this example, there is already tag FIN connect to company identifier F95:

3.5 Mappings in sales order integration (external identifiers)​

info

The following instructions are for companies using SO integration and Jakamo to receive orders from customer companies and send order confirmations to customers via Jakamo. Company mapping in sales order integration is following the rules of basic company mapping.

Special functionality for sales order (SO) integration mapping is the ability to create routing rules based on both, your identifiers and identifiers customers send to you with their Order message. This might be necessary if you have multiple customer numbers in your system to refer one customer in Jakamo, or if there is a need to separate customer orders based on e.g. the delivery location, sites, or other information in the order.

If you want to create special routing rules, fill in the external information fields when creating a new company mapping. Otherwise, leave External identifier empty. External information fields are the following:

  • External identifier: Fill in the identifier your customer sends to you via their Order. Define whether it is the external identifier customer's buyer customer party identifier or seller supplier party identifier.

  • External mapping field:

    • Buyer customer party: If the external identifier is the customer's buyer customer party identifier, select this.
    • Seller supplier party: If the external identifier is the customer's seller supplier party identifier, select this.

  • Compound rule member: If you want to create a compound rule by using both the buyer customer party identifier and seller supplier party identifier at the same time, select this and create the other half of the compound pair as its mapping. If mapping is part of the compound mapping, it means that for the compound rule to be fulfilled, the second mapping condition must also be fulfilled.

How do I define the necessary identifiers?

You may need to contact and discuss with your customer to find out which identifiers they are using, for example for delivery locations. Jakamo's support team can also help by defining identifiers. Contact Jakamo support (support@thejakamo.com) and we will help you.

3.5.1 Sales order company mapping example with external identifiers​

This is an example of SO integration mappings with external identifiers in use.

You want to have customer number 33333 on the order message you will retrieve to your internal system when your customer's order includes

  • buyer customer party identifier FI82828 and
  • seller supplier party identifier 7382729.

Create two separate mappings for that Company identifier 33333. Select Compound rule member selection for both two mappings. After that, compound rule mappings are shown as a pair in the company mapping list and both of the mappings need to be fulfilled to have identifier 33333 on the retrieved order. See the example below for the step-by-step instructions:

  1. Define in first mapping the external buyer customer party identifier and company identifier you want to have used.

  1. Define in the second mapping the external seller supplier party identifier and company identifier you want to have use with.

  1. After creating two separate mappings, compound rule is on. On the Company strings these compound rule mappings are having COMPOUND tag. Both of the compound rules must be fulfilled before order include identifier 33333 on the Order in sales order integration.

4. User mappings​

Jakamo needs to know the person who is using integration, for example creating orders or confirming orders. This is mandatory information to be define. Mapping between your system identifier for the user and Jakamo user account is needed so that Jakamo can set the Author user for the new item, or knows who has performing the action. All content in Jakamo is shared by the user.

Map your integration users in Jakamo Integrations settings page. Find all the existing user mappings listed under the User strings.

4.1 Add new user​

If you need to add new user who can share content via integration, you can add new user mapping from ADD USER button under the User strings. Fill correct User identifier and map it to the correct Jakamo user account:

  • Define User identifier: User identifier is identifier you have in your system to your user. User identifier is typically person's name, email address or other identifier (e.g. buyer code or purchasing group, seller number) you have in your ERP system for that user. If you have existing mappings, follow the same structure.
  • Jakamo account: Select the Jakamo user account from the account list you are creating a mapping for. Jakamo account list is a dropdown list of all the users you have in your Jakamo account.

You can leave Default user unticked. After saving the new user mapping from the OK, the user is able to share information via the integration.

4.2 Delete user mapping​

You are able to delete user mapping simply by using the trashcan icon. By deleting the mapping you are not deleting the user account from Jakamo. Also, these integration user mappings are not related to the user's Jakamo sign in credentials (username), which means that user's sign in credentials can be totally different than the identifier used with the user in the integration mappings. User can have an user account in Jakamo, but not necessary a mapping in any integration. This means user cannot be used via integration, for example user cannot create orders or confirm orders via integrations.

4.3 Default user​

Default user is used when creating new items automatically to Jakamo, on the other words, there is no person to sending out the content. For example, when your company is creating and sharing forecasts with partners via Jakamo. If necessary, define one user to be a Default user. This is not used in PO or SO integrations.

5. Integration credentials​

Consider to change from basic authentication to OAuth2.0 ❗

Please note that Jakamo supports OIDC/OAuth2 authentication and authorization, please consider moving to OAuth2 for improved security!

Integration credentials are managed in Jakamo if using basic authentication as an authentication methods. In that case, credentials are set separately for each integration you have in use. These credentials are used to authenticate to correct Jakamo API.

Change credentials from CHANGE CREDENTIALS button. You may see from the header which integration credentials you are updating, for example below SO integration:

Beware with the integration credentials!

Integration credentials are used by integrating systems and changing credentials may cause integrations to stop working if not done on purpose. Change integration credentials only if you are sure that you need to change integration credentials. You should not use this functionality if you need to change your personal password.

6. OAuth2.0 App registration​

OAuth2.0 authentication is a preferred way to authenticate to Jakamo APIs instead of basic authentication.

You may create and manage your OAuth2.0 applications on OAUTH2 APP ID section on Integration settings page in Jakamo.

Start registering a new application from Map OAuth2 application button and follow instructions given. Find step-by-step guide from our OAuth2.0 guidance.

Help & Support

Didn't you find what you were looking for? Send email to Jakamo support (support@thejakamo.com) and we will help you.