Introduction to EMS Platform Services

This topic introduces you to EMS Platform Services:

See Prerequisites and Requirements

What is EMS Platform Services?

EMS Platform Services is a Platform as a Service (PaaS) solution offering modern, RESTful APIs. Platform Services enables the development of multi-platform applications that can be customized, cloud-based, scalable, and easily integrated. It is a true middle tier, providing a business and resource layer that enables the central development of applications, reducing complexity and development time. Platform Services fosters innovation by ensuring easy maintenance and efficient management of an application's life cycle.

In the EMS architecture, databases exchange business logic directly with applications in the business tier. The Platform Services architecture creates an intermediary layer of business logic and resources that provides a buffer between the applications and EMS databases. Fixes, enhancements, and/or new features can now be dispersed simultaneously to all products through Platform Services.

ClosedGet Started with Integrations

Platform Services provides RESTful APIs that empower customers and partners to build custom, multi-platform applications connected to EMS. Any client/device accessing EMS Platform Services must be a registered Integration Client. The one exception is that anyone can access the public (open) API requests (/status, /health, /clientauthentication).

There are two types of Integrations:

  • Custom – Customer applications

  • Partner – Third-party EMS partner applications (e.g., 7PointsSolutions, Pepperdash, control concepts, etc.)

Partner and Custom types can be classified as either of these two client subcategories:

  1. User-based – User-based clients (EMS for Outlook) need to authenticate as a user to perform any actions. These clients need an integration client role with minimal access to the following API resources (above and beyond public resources):

    • /authentication

    • /logging

  2. Non-user Based – Non-user Based clients (EMS Kiosk, EMS Room Sign App) provide functionality independent of users but also support user-like functionality (such as Check-In and on-the-fly room reservations). These clients need a role with wider access.

ClosedStart the Integration Process

  1. Verify if you have a license for adding Integrations. EMS Licensing manages a numeric count of both Custom and Partner Integration Types. Contact your EMS Sales Representative for a license for EMS Platform Services. View Licensing Requirements

  2. Access Platform Services documentation (for example: https://Yourcompany.com/EmsPlatform/swagger). 

  3. Access admin portal for Platform Services (for example: https://Yourcompany.com/EmsPlatform/admin) to create a new Integration Client.  

    A Client ID and Secret pair will be generated.

  4. Platform Services requires a valid JWT Authentication token to call any of the API resources with the exception of /public, /status and /clientauthentication. Before making any API request, you must first call /clientauthentication with a Client ID and Secret pair generated in the previous step.

    • The Client token returned from calling /clientauthentication should be applied to the x-ems-api-token header for subsequent API requests.

      There can be multiple active instances of a particular client interacting with the Platform. All devices that share a client/secret will share a common authentication token. If the token expires, all devices will need to authenticate again to get a new shared token.

  5. For API resources that require an authenticated web user, your integration client will need to request a web user authentication token for that user. To acquire an authentication token, call the /authentication requests.

  6. The Web token returned from calling /authentication should also be applied to the x-ems-api-token header. This replaces the client token with a user token.

    To determine which token to use for the header field, see API documentation.

ClosedAPI Documentation

To view the API documentation, go to the Platform Services URL (for example: https://Yourcompany.com/EmsPlatform/swagger).

Base URL for All API Requests

Make all requests to URL for EMS Platform Services (for example: https://Yourcompany.com/EmsPlatform).

Date/Time Standards

All dates and times passed to the API requests follow RFC 3339 Standard and must be in UTC. 

All DateTimes follow the standard (e.g., 2008-09-08T22:47:31-07:00)

Common Response Codes

Response Code

Title

Meaning

200 Success Successful data call/pull.
400 Bad Request Server could not understand the request due to invalid syntax.
401 Invalid/Missing Client Credential User credentials are incorrect; invalid login info.
500 Server Error General status code that indicates the server encountered an unexpected condition and could not fulfill the request.
503 Service Unavailable Application pools are not currently enabled.
519 Server Internal Error System requirements are not met.

HTTP Request Methods

Method

Description

GET Requests data from a specified source.
POST Sends data to the API server to create or update a resource. Data sent to the server is stored in the request body of the HTTP request.
PUT Sends data to the API server to create or update a resource (similar to POST). PUT requests are idempotent and calling the same PUT request multiple times will always produce the same result. Calling a POST request repeatedly might have the side effect of creating the same resource multiple times.
DELETE Deletes the specified resource.
PATCH Applies partial modifications to a resource.