A generated OIH connector for the Meisterplan API API (version 1.2.0).
Generated from: https://api.eu.meisterplan.com/swagger.json
Generated at: 2021-05-31T09:20:31+02:00
The Meisterplan API provides machine-readable access to a Meisterplan system via an HTTP-based JSON REST interface.
This page will show you how to [get started](#section/Get-Started), and how you can [use the API to interact with your Meisterplan system](#section/General-Information).
## Reporting API
Want to load data into external BI tools? Create reports using the [Reporting API](https://help.meisterplan.com/hc/en-us/articles/360013641220), which provides data optimized for reporting.
## Versioning and Changes
We will continuously expand this API's functionality and add bug fixes (see the changelog [here](https://help.meisterplan.com/hc/en-us/articles/360024302652-Meisterplan-REST-API-Changelog)).
For best results, make sure your code can handle new JSON properties and does not depend on the order in which JSON objects are returned by the API, unless explicitly stated here.
## Support
If you have any questions, email us at [support@meisterplan.com](mailto:support@meisterplan.com) - we're happy to help!
[API Changelog](https://help.meisterplan.com/hc/en-us/articles/360024302652-Meisterplan-REST-API-Changelog)
[Meisterplan Help Center](https://help.meisterplan.com/)
[Meisterplan Terms of Service](https://meisterplan.com/terms-of-service/)
# Authentication
You will need a [Meisterplan system](#section/Get-Started/Meisterplan-System) and an [API Token](#section/Authentication/API-Token) for your
user.
You can then proceed to look at the [examples](#section/Get-Started).
Please also take a look at the [general information](#section/General-Information) which will give you an overview of how the API works.
## API Token
You can generate API tokens via the Meisterplan user interface.
Please take a look at the [help center](https://help.meisterplan.com/hc/en-us/articles/360028700752-REST-API-Manage-API-Tokens) how to generate API tokens.
Your token will look like this: `api-48eba51e5a8d43ed8a8daeba585b7093`.
Note that the letters `api-` are part of the token.
With this token, you can start building your integration.
If you need more help, see [this page](https://help.meisterplan.com/hc/en-us/articles/360028700752-Manage-REST-API-Tokens).
# Get Started
The following examples will use [cURL](https://curl.haxx.se/) to show you how to use the API from the command line.
## Meisterplan System
Start by getting an API token from your Meisterplan system (free trials available at [meisterplan.com/trial](https://meisterplan.com/trial/)).
The API URL of your Meisterplan system will depend on your region, either `https://api.us.meisterplan.com/v1/` for
the US or `https://api.eu.meisterplan.com/v1` for the EU.
You do not have to specify your system name in the URL, as it is already encoded in the [API token](#section/Get-Started/API-Token).
Let's assume you have a [Meisterplan system](#section/Get-Started/Meisterplan-System) in the US and the [API token](#section/Get-Started/API-Token) `api-xxx`.
## Headers
To perform your own requests against the API, you must provide an `Authorization` header on every HTTP request.
```
Authorization: "api-xxx"
```
An HTTP status code 401 will be returned if you are not authorized to access the API.
Additionally, all `PATCH` and `POST` requests require you to specify the accepted MIME type with the following header:
```
Content-Type: application/json
```
## Resources
**Please note**: The following examples assume you're running an [`sh`-compatible](https://en.wikipedia.org/wiki/Bourne_shell) shell or `cmd.exe` and have access to the [`curl`](https://curl.haxx.se/) command. Using `curl` in [MicroSoft PowerShell](https://docs.microsoft.com/en-us/powershell/) will **not** trigger the `curl` command, but will instead call [`Invoke-RestMethod`](https://docs.microsoft.com/en-us/powershell/module/Microsoft.PowerShell.Utility/Invoke-RestMethod?view=powershell-5.1), which has an incompatible command argument syntax. Using `curl` is not a necessary prerequisite to using the Meisterplan REST API, and you are free to use any tool that suits your requirements.
The following call will [create a new resource](#operation/createResourceUsingPOST) in your Meisterplan instance:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/resources" \
-H "Authorization: api-xxx" \
-H "Content-Type: application/json" \
--data "{ \"lastName\": \"Stine\", \"firstName\": \"Brandon\" }"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/resources" ^
-H "Authorization: api-xxx" ^
-H "Content-Type: application/json" ^
--data "{ \"lastName\": \"Stine\", \"firstName\": \"Brandon\" }"
```
The answer will look similar to the following (the internal and external IDs will be different for your response):
```
{
"id" : "50703a7a-9285-4ffe-9e29-47187c454ade",
"firstName" : "Brandon",
"lastName" : "Stine",
"externalId" : "96bb0fbc-a7e0-4ee3-b456-dbf390960268",
// … more fields
}
```
You can [retrieve your new resouce](#operation/getResourceByIdUsingGET) using its ID:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/resources/50703a7a-9285-4ffe-9e29-47187c454ade" \
-H "Authorization: api-xxx"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/resources/50703a7a-9285-4ffe-9e29-47187c454ade" ^
-H "Authorization: api-xxx"
```
You can [update a resource](#operation/updateResourceUsingPATCH) using the `PATCH` method. Let's give Brandon an email address:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/resources/50703a7a-9285-4ffe-9e29-47187c454ade" \
-H "Authorization: api-xxx" \
-H "Content-Type: application/json" \
--data "{ \"emailAddress\": \"brandon.stines@example.com\" }" \
-X PATCH
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/resources/50703a7a-9285-4ffe-9e29-47187c454ade" ^
-H "Authorization: api-xxx" ^
-H "Content-Type: application/json" ^
--data "{ \"emailAddress\": \"brandon.stines@example.com\" }" ^
-X PATCH
```
You will notice that the email field in the response is now set to the new email address:
```
{
"id" : "50703a7a-9285-4ffe-9e29-47187c454ade",
"firstName" : "Brandon",
"lastName" : "Stine",
"emailAddress" : "brandon.stines@example.com",
// …
}
```
You can also [list all available resources](#operation/getAllResourcesUsingGET) by omitting the ID:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/resources" \
-H "Authorization: api-xxx"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/resources" ^
-H "Authorization: api-xxx"
```
The answer will look like this:
```
{
"items": [
// …all resources
]
"_pagination": {
"after": {
"cursor": "ZjkyYjU1MDItNTAwYi00Yzg1LWEwOGItMzllZWU1NWE4ZTlk"
}
}
}
```
The resource endpoint is [paginated](#section/General-Information/Pagination).
Let's get some more resources:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/resources?pageSize=16&pageAfter=MDAzNWQ5MDctOTZkNi00MzdjLWE4MmUtMzNiZDBjNjdiNmM1" \
-H "Authorization: api-xxx"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/resources?pageSize=16&pageAfter=MDAzNWQ5MDctOTZkNi00MzdjLWE4MmUtMzNiZDBjNjdiNmM1" ^
-H "Authorization: api-xxx"
```
If no more resources are available in your system, the request will return an empty list.
## Projects and Scenarios
[Projects](#tag/Projects) are linked to their [scenarios](#tag/Scenarios) in Meisterplan.
You can only address projects through their scenario ID.
You can query Meisterplan for [all scenarios](#operation/getAllScenariosUsingGET):
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/scenarios" \
-H "Authorization: api-xxx"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/scenarios" ^
-H "Authorization: api-xxx"
```
The answer will look like this:
```
{
"items" : [ {
"id" : "2b45a678-8bd3-4e5e-acd9-1e817b530204",
"name" : "Proposed Portfolio going forward"
}, {
"id" : "7a36777f-00d7-dd0b-2468-95aa94f90e63",
"name" : "Plan of Record"
} ]
}
```
You can then use a scenario's ID to retrieve a project.
Note that the special scenario *Plan of Record* always exists.
You can use it in the URL instead of using its ID.
Let's [retrieve all projects](#operation/getAllProjects-AMtyOPcUsingGET) in the *Plan of Record*:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/scenarios/PlanOfRecord/projects" \
-H "Authorization: api-xxx"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/scenarios/PlanOfRecord/projects" ^
-H "Authorization: api-xxx"
```
You can also create new projects and edit existing ones just like you can resources.
Let's [create a new project](#operation/createProject-QWGM0WIUsingPOST) in the *Plan of Record* with Brandon as its project manager:
`sh`-compatible shell:
```
curl -s "https://api.us.meisterplan.com/v1/scenarios/PlanOfRecord/projects" \
-H "Authorization: api-xxx" \
-H "Content-Type: application/json" \
--data "{ \"name\": \"Company-wide roll-out of Meisterplan\", \"start\": \"2020-01-31\", \"finish\": \"2020-02-14\", \"manager\": { \"id\": \"50703a7a-9285-4ffe-9e29-47187c454ade\" } }"
```
Windows Console (`cmd.exe`):
```
curl -s "https://api.us.meisterplan.com/v1/scenarios/PlanOfRecord/projects" ^
-H "Authorization: api-xxx" ^
-H "Content-Type: application/json" ^
--data "{ \"name\": \"Company-wide roll-out of Meisterplan\", \"start\": \"2020-01-31\", \"finish\": \"2020-02-14\", \"manager\": { \"id\": \"50703a7a-9285-4ffe-9e29-47187c454ade\" } }"
```
Notice how we've provided Brandon's *internal ID* to link him to the new project as its project manager.
# General Information
## HTTP Methods
The Meisterplan API recognizes the HTTP methods: `POST`, `GET`, and `PATCH` and `DELETE`.
They correspond to the _create_, _read_, _update_ and _delete_ operations.
The endpoints for creating and updating an entity will always respond with the newly created or updated entity in their response payload.
If successful, `POST` endpoints will respond with HTTP status code `201` and `PATCH` with endpoints with `200`.
Deleting an entity will result in no body and an HTTP status code `204`, if successful.
### HTTP Method Override
If your firewall does not permit certain HTTP methods from being executed, you may override the HTTP request method with the `X-HTTP-Method-Override` header. The following request:
POST /v1/resources/123 HTTP/1.1
X-HTTP-Method-Override: PATCH
will be interpreted as a `PATCH` request against the resource with the id `123` by the server.
## IDs
All entities carry an internal Meisterplan ID in the JSON property `id`, which can be used for reference in other requests, or for updates and deletions.
Additionally, Meisterplan allows you to set a **unique** `externalId` for some entities.
The `externalId` can be used to cross-reference a Meisterplan entity with your own system.
The `externalId` is never used by Meisterplan.
## Pagination
Some endpoints return paginated data.
In order to access the next page, an opaque cursor is provided in the response to your `GET` request, which can be passed as a query parameter `pageAfter` on a subsequent request.
You can control the page size with the `pageSize` query parameter.
The following URL will return 16 items following the given opaque cursor:
```
https://api.us.meisterplan.com/v1/resources?pageSize=16&pageAfter=MDAzNWQ5MDctOTZkNi00MzdjLWE4MmUtMzNiZDBjNjdiNmM1
```
## Filtering
In order to find a certain entity, all paginated endpoints allow for filtering using the `filter` query parameter.
The filter will look for entities matching _all_ of the provided values _exactly_.
All properties of the filter object are optional.
An empty filter results in all entities being returned.
Filter values of `null` are ignored.
The following URL will retrieve all resources with the external id `brandon.s`:
```
https://api.us.meisterplan.com/v1/resources?filter={"externalId":"brandon.s"}
```
Note that depending on your environment, you may need to URL-Encode the filter:
```
https://api.us.meisterplan.com/v1/resources?filter=%7B%22externalId%22%3A%22brandon.s%22%7D
```
Not all fields can be used in a filter.
To see which fields are available, refer to the endpoint's documentation.
Look for the `filter` query parameter and the example model, which lists all available fields.
## Updating Fields
Fields of existing entities can be updated via HTTP `PATCH`. In order to delete a field’s content, or replace it with its default value, if any, set the field to `null`. Only the specified fields will be changed. Fields not specified in the `PATCH` body will not be affected.
Nested objects **are not** deleted recursively by setting their parent property to `null`. Delete the respective sub-fields by individually setting them to `null`. Fields whose values are objects with only **one** property (such as a resource’s `calendar` or `primaryRole` whose only sub-field is `path` and `id`, respectively) **are the exception**. You can delete a resource’s association with a given calendar or primary role by setting `{ "calendar": null }` or `{ "primaryRole": null }`.
## Error Handling
The error messages generated by the Meisterplan API follow the [JSON API specification](https://jsonapi.org/examples/#error-objects) on error objects.
If your request was not valid, HTTP status code 400 will be returned, along with a JSON object detailing the cause of the error.
If you did not have sufficient permissions to perform the request (e.g. attempting to access a field for which you have no permission), HTTP status code 403 will be returned.
## Dates
### Format
The Meisterplan API uses the [ISO8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) for all dates:
`YYYY-MM-DD`
For example, September 27, 2020 is represented as `2020-09-27`.
The earliest possible date is `1970-01-01`. The latest possible date is `2079-07-02`.
### Time Periods
Start dates of time periods are interpreted as the beginning of a day.
For example, `2020-09-27` will be interpreted as September 27, 2020 at 12:00am.
Finish dates of time periods are interpreted as the end of a day.
For example, `2020-09-27` will be interpreted as September 27, 2020 at 11:59pm.
## Rate Limiting
In order to prevent outages and to make sure the API is fast for everyone, the Meisterplan API will rate limit requests.
The API allows for at least 300 requests per minute, per user.
Please ensure you do not call the API with multiple concurrent requests, as some requests cannot be performed in parallel.
If you have exceeded the rate limit, an HTTP status code 429 will be returned.
If you happen to be rate-limited, we recommend you use [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) method for retries.
We reserve the right to change these guidelines to ensure the API's availability.
Supported authorization schemes:
- API Key
Creates a resource by the given fields and returns the newly created.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Tags: Resources
Returns the individual resource specified by the given ID.
Tags: Resources
resourceId- required - Internal Meisterplan identifier
Delete the resource specified by the given ID. If the resource with the given ID does not exist, the request fails.
Tags: Resources
resourceId- required - Internal Meisterplan identifier
Perform an update on a resource specified by the given ID.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Tags: Resources
resourceId- required - Internal Meisterplan identifier
You can use this request to replace the calendar deviations of a resource for a certain period of time.
This time period can be defined using the root start and finish attributes of the request.
Under the deviations property all deviations of a resource can be specified using a list.
It should be noted that all deviations in the specified period are overwritten by the deviations listed in the deviations property.All deviations are flattened into a sequential structure. Cases of overlapping deviations will be resolved by giving precedence to deviations occurring later in the array.
- If null is used for the start period and end period, all calendar deviations of the resource are overwritten
- If only the start date of the period is defined, all deviations starting from this time will be overwritten
- If only the end date of the period is defined, all deviations up to that point will be overwritten
- If null is used for the start and/or end date of a calendar deviation, the deviation is assumed to last from or until the root start or finish date specified above.
Tags: Resources
resourceId- required - Internal Meisterplan identifier
Returns the created role on success.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Tags: Roles
Returns the individual role specified by the given ID.
Tags: Roles
roleId- required - Internal Meisterplan identifier
Perform an update on a role specified by the given ID. To do a partial update, only the updated fields need to be sent. To delete a field value, the field must be sent with an explicit null value. Fields with a default value will be reset to their default when set to null.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Tags: Roles
roleId- required - Internal Meisterplan identifier
Returns the individual scenario specified by the given ID.
Hint:
You can use "planOfRecord" as the ID for the plan of record scenario.
Tags: Scenarios
scenarioId- required - Internal Meisterplan identifier
This endpoint updates the priorities of projects and programs. Please consider that updating the priority of a project that is within a program results in unassigning the project from its program.
Tags: Priorities
scenarioId- required - Internal Meisterplan identifier
Creates a program with the given fields and returns the newly created program.
Tags: Programs
scenarioId- required - Internal Meisterplan identifier
Deletes a program specified by the given ID.
Tags: Programs
programId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Perform an update on a program specified by the given ID.
Tags: Programs
programId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Creates a project with the given fields and returns the newly created project.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Custom fields are defined as properties of the customFields object.
The property name of a custom field corresponds to its column name. A custom field is an object containing a value.
The value can be of type string, number or boolean depending on the type of custom field. You can view all available custom fields with their respective
column names in your Meisterplan system.
For custom fields of type string, text, lookup or url, the value is of JSON type string.
For custom fields of type integer, decimal or currency, the value is of JSON type float.
For custom fields of type boolean, the value is of JSON type boolean.
Example:
"customFields":{
"cust_stage_gate":{
"value": "New"
}
...
}
Projects may be assigned to a program, or they can be given a rank category. It is not possible to assign a
project to a rank category and a program at the same time. Assigning an existing project to a rank category will
unassign it from any program it may be assigned to. Assigning an existing project to a program may mean that its rank
category changes, if the target program is in a different rank category.
It is currently not possible to prioritize projects within a program.
Tags: Projects
scenarioId- required - Internal Meisterplan identifier
Returns the individual project specified by the given ID.
Tags: Projects
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Deletes a project in a given scenario.
Tags: Projects
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Perform an update on a project specified by the given ID.
Paths delimited by / (e.g. in calendars and OBS unit paths)
may define path segments which contain / by escaping with //. E.g. the path
Europe/Berlin//Amsterdam will be interpreted as ['Europe', 'Berlin/Amsterdam'].
An uneven amount of slashes will be interpreted as the following segment starting with one or more slashes.
Custom fields are defined as properties of the customFields object.
The property name of a custom field corresponds to its column name. A custom field is an object containing a value.
The value can be of type string, number or boolean depending on the type of custom field. You can view all available custom fields with their respective
column names in your Meisterplan system.
For custom fields of type string, text, lookup or url, the value is of JSON type string.
For custom fields of type integer, decimal or currency, the value is of JSON type float.
For custom fields of type boolean, the value is of JSON type boolean.
Example:
"customFields":{
"cust_stage_gate":{
"value": "New"
}
...
}
Please consider that an update of the finish date of a project deletes all milestones and allocation segments that exist after the new project finish date.
Tags: Projects
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Creates or updates allocations for a given project.
Tags: Allocations
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the individual allocation specified by the given ID.
Tags: Allocations
allocationId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Deletes an allocation in a given project of a scenario.
Tags: Allocations
allocationId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Perform an update on an allocation specified by the given ID.
Tags: Allocations
allocationId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the newly created financial event.
Tags: Financials
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the individual financial event specified by the given ID.
Tags: Financials
financialsId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Deletes a financial event in a given project of a scenario.
Tags: Financials
financialsId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Updates a financial event by ID in a given project of a scenario.
Tags: Financials
financialsId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the newly created milestone
Tags: Milestones
projectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the individual milestone specified by the given ID.
Tags: Milestones
milestoneId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Deletes a milestone in a given project of a scenario.
Tags: Milestones
milestoneId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Perform an update on a milestone specified by the given ID.
Tags: Milestones
milestoneId- required - Internal Meisterplan identifierprojectId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Returns the capacity segments for the role specified by the given ID. Returns an empty list if no capacity segments exist.
Tags: Role Capacities
roleId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
Updates the capacity segments for the role specified by the given ID. To erase all capacity segments, send a segment without start or finish and 0 capacity
Tags: Role Capacities
roleId- required - Internal Meisterplan identifierscenarioId- required - Internal Meisterplan identifier
: meister
All files of this connector are licensed under the Apache 2.0 License. For details see the file LICENSE on the toplevel directory.