A couple of weeks ago we requested feedback regarding the BeLazy API in this blog post. We are very thankful to those who replied to our requests, and we are happy to announce the general availability of the API for business management systems. We believe that we made them very easy to use, and this article – which should be understandable for linguists, company owners, project managers who work with a proprietary system and developers – describes the workflow for setting up an integration.
What are the BMS APIs?
Until now, BeLazy worked seamlessly only for users of XTRF and Plunet. However, many companies have proprietary business management systems that they would like to integrate with their customers’ vendor portals. Instead of creating several connections, they can leverage the entire BeLazy functionality with just one single integration.
If you have a proprietary business management system, the BMS APIs are for you. You can also use these APIs if you are a business management system vendor and want to integrate your system with BeLazy out of the box.
Are the BMS APIs easy to integrate with?
Yes, they are! We know that many vendor portals don’t have APIs to build integrations. This is why we have worked this around: BeLazy now provides you the API. Our goal is to make the integration through BeLazy easier than any vendor portal integration could be.
Building integrations usually gets complicated when it comes to exception handling and value mapping. BeLazy has a strong integration framework and a simple user interface that takes care of the majority of these problems, so you don’t have to code anything from scratch.
Of course, sometimes there is a need for small error handling (such as what happens if the authentication is not working or if the connection does not get through), but this article describes the most common error sources. We have also provided users with a test environment with unlimited access to sample projects to safely develop their integration — this is what many vendor portal owners can’t provide.
How much does this cost?
You can use the BeLazy APIs for free. You only pay for the cost of the integration development. Once you start using the integration, you will be charged the standard BeLazy fees after projects that were successfully created in your business management system.
We also provide technical support during development, so let us know if you get stuck during the process. We believe integration time should not take more than a few working days.
What’s the recommended way to start development?
- Which account should I use? You can use your BeLazy account, but due to permission restrictions, we recommend creating a Google account that both the developer and the project manager can access, and configure BeLazy with this one.
- Developing and testing: When it comes to developing the integration and testing the code, there is no need to set up a live vendor portal. It can be done using BeLazy’s complimentary test environment.
- Connections to vendor portals: Configuring a single connection to one vendor portal is enough for validation or user acceptance testing purposes. If you add more vendor portals later to BeLazy, they’ll work without any further development.
- Changing account: If you later want to change the BeLazy account to another Google or Microsoft account, your developer needs to replace the access token — it takes no longer than a few minutes.
How do the APIs work?
Step 1: Prepare your Language, Specialization, Service and Rate values
Who should this? The developer extracts these lists from your BMS, without using BeLazy.
We designed the API keeping simplicity in mind, so that it can be applied to almost any system. For this reason, during configuration, you need to enter a number of values that hardly ever change in the BMS. These values are entered in the form of a JSON array containing objects that consist of a label and a value.
It may sound more complicated than it actually is. Open a text editor, put “[“ at the beginning of the file, “]” at the end of the file, and several of the segments like the example below, one after the other:
{
“label”: “Spanish (Spain)”,
“value”: {
“type”: “IntegerNumber”,
“value”: 15
}
},
Note: Remove the comma after the closing } for the last item
Every entry is a label-value pair. Labels (e.g. Spanish (Spain)) are what appear on the screen in BeLazy when you are mapping them. The value is the ID which is used by your BMS’s code to refer to this item (15). The value consists of the type, which is typically IntegerNumber or Text and the value which is the actual ID.
BeLazy maps the values received from the vendor portals to your internal values and your BMS will receive this mapped value. For example, if the job’s target language is Spanish in the vendor portal, which you would enter into your BMS as Spanish (Spain), this mapping will be done by BeLazy, and your system will automatically receive the value 15 – you don’t have to write the logic yourself to handle this.
The pre-populated fields are:
- Your language codes. These may be identified by a number or a code in your BMS.
- Your list of specializations, areas of expertise, whatever you call the differentiator between e.g. a medical and a financial translation. These are also numbers or text strings in your BMS. If your system does not register this, just enter one value, and map all of the possible values to that one.
- The list of services, workflows, task types. Different systems handle these differently, but imagine the difference between translation and translation-editing-proofreading, or machine translation post-editing or transcreation.
- The rate values. One set is a list of different value types in one kind of analysis. For example, you need two sets if your BMS handles both memoQ and Across analysis (for the record: memoQ and many other tools do 85-94%, Across has 90-99%, 80-89%).
You will need these four JSON files during the configuration. You can see examples to this in the API reference.
Step 2: Login to BeLazy
Who should do this? Either the project manager or the developer
Using your Google or Microsoft ID, create an account in BeLazy and log in.
Now, you can set up your connection to have a deeper insight of what BeLazy can do for you. Get the access token for the API authentication, which the developer needs to start working on the API. How to get the token is described in step 4.
Step 3: Set up your system
Who should do this? Normally the project manager would do this, but it makes sense for the developer to see it. The project manager needs the configuration files.
Set up a connection to a vendor portal, and start automation. When entering the business management system, enter the URL to your system. BeLazy will offer a link you can click to register your own system if it does not recognize the BMS.
Click there, and paste the four JSON files specified in step 1.
The last bit is the configuration of the webhook, which is an optional step. We’ll go over this later.
Once you have uploaded the JSON values, you’ll have to do the mapping between the vendor portal and your business management system (i.e. the JSON values) as you do it “normally” in BeLazy.
Step 4: Get an access token.
Who should do this? Either the project manager or the developer can do it. The developer will need the token, but it’s a simple string that can be sent to the developer.
The last configuration step on the interface is to generate an access token. This is what the caller will need to include in the header of the request to be able to receive the projects from your vendor portals configured here. Open the profile menu in the top-right corner, and select the menu item for tokens.
Step 5: Implement the API calls
Who should do this? The developer
There are only two important queries: List Projects, and Acknowledge Project Creation. You can also request a single project by its ID, but the List Projects call will return the full project structure anyway. The documentation is available here.
List Projects groups all the accepted but not acknowledged projects in BeLazy. It gives you a project ID, and all the metadata with three mappings: origin, beLazy, and destination.
- Origin: contains the values from the vendor portal
- beLazy: contains an internal mapping
- destination: contains the values that BeLazy mapped based on your JSON files and mapping settings, prepared for use in your BMS.
It is recommended to populate your system with the destination values. The other values are included for flexibility, so that developers have access to all values exposed by the source vendor portal.
Once you have successfully created the project in your system, you must acknowledge it. Please note that if you don’t do this, we will limit the use of the system. Acknowledging is easy: just call a URL including the projectID, and optionally send back your external ID and the URL if your system is web-based. If you return the URL, the PM will be able to click through from BeLazy directly to the corresponding project in your BMS.
One of our problems with implementing vendor portal integrations is receiving test projects in real-life systems. Believe us, we know what we are talking about… We have worked hard to make this as easy as possible for you : if you include the X-BeLazy-Test HTTP header in your calls (the value does not matter), you’ll always receive some sample project information. During the development process, you can test with this, this test data will never run out of projects. Finally, remove the special header from the code, and validate your integration with real-life information.
Step 6: Implement the webhook (optional)
Who should do this? The developer
A webhook, also known as a callback URL, allows BeLazy to call the API of your system to indicate that it should query the projects as a new project had been accepted. If you have already gone through steps 1-4, your integration with BeLazy will be able to query newly accepted projects and publish them to your BMS at certain intervals, e.g. every 15-30 minutes.
If you implement the webhook, the projects can be created in your BMS immediately once you press Approve in the BeLazy interface, or once the BeLazy system automatically approves a project. BeLazy can send a REST call to a predefined URL with predefined content. Use the Playground in the documentation to test if it works. Accepting calls from the outside world is generally not easy. To see how it works, before you start creating holes in your firewall, you can utilize online tools like https://www.mocky.io/. Then you can try to send a call into your own system and verify that it is well received. Sometimes, your browser may bump into security related limitations, like in the screenshot below. In this case you will need to edit the security settings on your side. Once it works, set up the callbacks by editing the automation in the BeLazy interface.
Step 7: Start receiving projects… and don’t forget to add all your connections
Who should do this? The happy BeLazy customer 🙂
Error handling scenarios
Most errors are handled by BeLazy, so you don’t need to prepare for all the peculiarities of the vendor portals, but there are some things you should be aware of and prepare for:
- BeLazy is down (low priority). We continuously monitor BeLazy and the uptime is 100%. However, we can’t guarantee that there would never be a moment when BeLazy or any of its services go down. If you are querying the projects regularly, the worst thing that can happen is having to wait until the next scheduled time comes. BeLazy also conveniently shows an hourglass icon next to the projects that were approved but not yet created in your BMS, so if a project is urgent, you can manually create it and delete it when it’s automatically created later. Suggestion: don’t prepare with robust solutions for this scenario.
- The access token was revoked (low to medium priority). Your code uses an access token which may be deleted from the BeLazy user interface. It’s a low risk if you tell your team not to touch it, but decide whether this needs to be handled programmatically.
- Language codes, rates, specializations, services change (high priority, may be process, not code). Whenever you change these lists, you should reconfigure your BMS in BeLazy. Otherwise BeLazy still gives you the assignments to the old lists. If the value is still there (e.g. you changed Spanish (Latin America) to Spanish (International) or IT to Information Technology or Software), no problem, but if the value is gone, your project may not be created. There are two ways to prepare: 1. For any change in these lists, include the BeLazy check in your checklist. 2. Solve this programmatically by giving an error message if the project creation faces a problem.
- Contact person, end customer, user ID does not exist (high priority, in code). If you just include this data as a string, no problem, but you may receive new contact persons, end customers, and your old PMs may leave the company. Pay attention to handling these situations.
- Currency does not exist (medium priority, in code or through contracts). This is a realistic scenario you may need to prepare for. We don’t convert currencies. Of course, your sales team can handle this best by notifying you up front if they foresee jobs in a different currency. Currency mapping needs to be handled by you.
- Customer does not exist (medium to high priority). A connection is normally bound to a customer, and the mapping here is your job. When you add a connection in BeLazy, it will have an ID. You should define a strategy to prepare for adding new customers – either you can do it in the code, or create an interface for mapping a BMS customer to a BeLazy ID (e.g. a field next to the customer with the BeLazy ID).
