-
Notifications
You must be signed in to change notification settings - Fork 6
Getting started
The easiest way to start exploring and using PlanMill API is using a free API tool called Postman, although you can use any client.
You can use of course any tools you would like, but this guide is written using Postman as example.
We recommend free Postman extension to Chrome or Mac for easy access to trying out our API and to generate the client code in your favorite programming language.
Chrome and Mac apps available: https://www.getpostman.com/
We are using RAML standard four our API design and documentation, so you can directly use our docs for your API tools.
Clone this repository to your computer (or just download a .zip file)
Most tools provide ways to use the RAML documentation directly, so does Postman. For other tooling, check http://raml.org/projects/projects
There are a few files in the repository which don't belong to the actual docs, so only use .raml, .schema and .sample for this step.
Import the RAML and JSON files to Postman.
This will get all of our API calls as an easy collection that you can start using immediately
The url to the API is for Cloud customers
https://online.planmill.com/:instance/api/1.5
If you have imported the API as a collection to Postman in the previous step, Postman has automatically converted the urls to use URI (path) parameters. So the url in Postman looks like this with ":instance" as the path parameter:
https://online.planmill.com/:instance/api/1.5/me
Just click "Params" to edit the parameters and set the instance name to your own.
If you are not yet a PlanMill customer, go to https://www.planmill.com/plans-pricing/ , pick a suitable product package and register for Free Trial using your business email account.
If you want to test only the api. go to Request access to OpenAPI instance
We use Oauth2 / OpenID Connect in PlanMill for authentication so you need to register a client in PlanMill to get API access.
We have selected you the first API call you should make:
https://online.planmill.com/:instance/api/1.5/me
This API call is very safe as it only gets you your own user information and doesn't make any changes nor requires any parameters.
Select this GET /me -endpoint from the Postman Collections -tab under PlanMill -collection. Remember to set the instance -parameter to your instance.
Prerequests : Create new role for API access and create new user and assign that role. Add access to new role that you created to use api. HRM -> Users -> View user api key (Employeedirectory.Users view api key) If above access right is not added, you will get "401 Unauthorized" when you perform registration.
Go to https://online.planmill.com/:instance/api/registrations.jsp
or
"People -> My Page -> Registerations" link in Planmill
- Provide "Allowed redirect URIs" as https://www.getpostman.com/oauth2/callback
- To automatically refresh access tokens select "Refresh secret, if Client ID exists" as "Yes" (Default) otherwise set it as "No".
- Click on Register and collect the "Current registrations" section's newly generated ClientId and ClientSecret which we are going to use it in Postman to authenticate planmill api.
In Postman, under the api call url, find the Authorization -tab. Select "OAuth 2.0" from the "Type" list. For further information see Postman guide section Oauth2.
-
Click "Get new access token"
-
Enter authentication details as below
- Authorization url: https://online.planmill.com/:instance/api/oauth2/authorize
- Token url: https://online.planmill.com/:instance/api/oauth2/token
- Client id: copy from the client registration page (Step 1)
- Client secret: copy from the client registration page (Step 1)
You don't need to set scope (if empty it will default to the only allowed scope "openid" since we are using OpenID Connect).
Leave Grant type as "Client Credentials".
- Click "Request token", a login window opens
- Log in to your PlanMill instance with the authorized credentials
- After successful login, the login window closes and you have a new access token
- Select the token you just created, select "Add to Header" and click "Use token". Postman will add the token to the request headers as "Bearer"
- Done! You can make as many calls you would like in the next 60 mins while the access token is valid. After that repeat steps 2-6 to get new token (Postman will remember your settings and you don't need to register another client).
In case you use some other client application or need to get the access token programmatically, here are the example requests:
Use the "Generate code" in Postman for generating the API request in the programming language of your choice like Java, PHP, Node.js etc.
Implementation example in Java language is available here: https://github.com/planmill/api-data-helper