Integrations
This page and integration instructions is for all Jakamo companies using Jakamo via any 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 creating a new mapping for new users or business partners, or delete old or incorrect mappings.
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
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 correct 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.
In most cases, Company identifier and selecting the Jakamo company are the only things needed to do when creating mew company mapping. If you know that you need additional routing together with your customers or suppliers with Compound or Tag rules, then you may use them according the compound rule instructions. Otherwise stick with company identifier and Jakamo company.
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 an 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)
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:
4. User mappings
User mappings are essential for Jakamo to identify who is performing actions like creating or confirming orders. This ensures proper tracking and accountability within the system. 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 know who has performed the action. All content in Jakamo is shared by the user.
In the Jakamo test environment, you will probably test integration with 1 or 2 buyer or seller credentials, but in production, each buyer or seller needs to have their own Jakamo user account. They don’t need to log in to Jakamo to handle orders or order confirmations, but Jakamo needs to know who places the order or order confirmation. It’s enough that the Jakamo user credentials are created.
Map your integration users in Jakamo Integrations settings page. Find all the existing user mappings listed under the User strings.
Find special user mapping instructions for PO integration and SO integration from Jakamo Technical Documentation.
4.1 Add new user mapping
If you need to add a new user who can share content via integration, follow these steps:
-
Identify the user: Determine the user identifier in your system. Determine the user identifier in your system. Users are typically identified by whether they are using Jakamo to purchase or sell goods (e.g., name, email, buyer or seller code).
-
Access Jakamo integrations settings: Navigate to the Jakamo Integrations settings page.
-
Add new user: Click on the
ADD USERbutton under the User strings section. -
Fill in user information:
- 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 unselected. 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
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:
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.
Didn't you find what you were looking for? Send email to Jakamo support (support@thejakamo.com) and we will help you.