The Juniper Support Service Request APIs are a well-defined set of REST APIs that enable Clients (Juniper Customers and Partners) to integrate their Support CRM/ticketing systems with Juniper’s Support CRM system. As part of this B2B integration Clients can:
- automatically create a Service Request (SR) in Juniper’s Support CRM system based on a case/ticket/incident in their system,
- manage the SR lifecycle via this API channel for example to; update the case, attach files, escalate the case, request case closure,
- receive asynchronous updates to the SR made by Juniper Support engineers and/or other channel updates without the need to poll.
Clients integrating their support CRM/ticketing system with Juniper via this channel avoid duplication of the data. The integration simplifies the process and reduces effort as users only need to enter data once in their CRM/ticketing system.
The Case API is available to customers who have an active Juniper Care or partner equivalent support contract. The Support Service Request APIs Overview video provides an overview of the API highlighting key aspects and details.
Note: Juniper uses Case and Service Request interchangeably.
|Account ID||Juniper Account identifier. Registered users can be associated to one or more Accounts.|
|API||Application Programming Interface|
|AppID||API Key provided by Juniper. Required to be provided in each API request.|
|Client||Customer or Partner integrating their Support CRM system with Juniper’s Support CRM system using this API channel.|
|CRM||Customer Relationship Management system|
|Host||Juniper’s CRM system and AWS S3 storage space.|
|REST API||API based on Representational State Transfer using HTTP/HTTPS.|
|Service Request (SR)||Support case in Juniper’s Support system. Case and Service Request are interchangeable in this document.|
|UserID||The registered UserID (provided as part of onboarding) the Client uses in request API calls.|
High-level API Model
The following illustrates a high-level view of the Case API framework. This framework allows you to integrate your ticketing system with Juniper’s Support CRM system. This a B2B integration. Two authentication mechanisms are supported. An authentication phase followed by a request/response is the typical flow.
The architecture supports a push notification model. Clients receive asynchronous updates immediately on case updates. Push Notification is also called the Publish/Subscribe model. A polling model is not supported. See Push Notifications.
There are 10 Case APIs and two push notifications. See Case API Descriptions for an overview.
The APIs are RESTful, the data format is JSON and the transport is HTTPS (TLS 1.2+).
Create Case Model
The following shows the API interactions for the
createSR API request.
Update Case Model
The following shows the API interactions for the update API requests (
Query Case Model
The following shows the API interactions for the query API requests (
Rate Limit is defined as the maximum number of Case API requests that can be submitted per hour. Each client will be permitted a maximum of 300 requests/hour. Upon receipt of a request the rate of requests is calculated and if it exceeds 300 requests/hour the request will not be processed and a rate limit exceeded error is sent.
Case API Descriptions
Create a Service Request and associate it with the customerCaseNumber from the request.
Note: createSR response will NOT contain the Juniper serviceRequestNumber. The publishSR sent asynchronously to the client endpoint after the creation of the service request includes the serviceRequestNumber along with the customerCaseNumber sent in the request. The customerCaseNumber must be unique in each createSR request.
|2||updateSR||Update the SR with a Note, modify the Synopsis, Problem Description provided during createSR, change priority, change the followup method, set/modify routerName and overwrite cc email with a new cc list.|
|3||escalateSR||Escalate an SR specifying a reason code and including an escalation note.|
|4||closeSR||Provide confirmation to Juniper Service Request Owner to close the SR.|
|5||getFileUploadToken||Attaching a file to an SR is a three-step process. First step is to obtain a stsToken from Juniper using this API. The response contains the required token information for the Client to use with AWS S3 SDK to upload files to Juniper's AWS S3 storage (see Amazon's Using The MP Java API documentation.).|
|6||attachFile||Pass information about the uploaded files. After successfully uploading the file or files to Juniper's AWS S3 storage, call this API to link the file to the SR for access by Juniper's agents.|
|7||querySRdetails||Request SR details using the CCN and SRID. The response contains SR details, including lists of notes, attachments, RMAs, and linked content, plus the full content of the latest 5 notes.|
Request the contents of a note in an SR by SRID and NoteID. The response is note contents for that NoteID in the specified SR.
Note: Bulk extraction of all notes is NOT supported.
|9||queryRMAdetails||Request RMA details using the CCN, SRID, and RMA number. SRs can have multiple RMAs. You must call queryRMA for each RMA in the SR. The response contains RMA details.|
|10||updateRMA||Update the carrier and waybill number of RMA defective item when you ship the defective item back to Juniper.|
|11||publishSR||Based on certain SR events, Juniper publishes SR details, including list of notes, attachments, RMAs and linked content, plus the full content of the latest 5 notes. The payload is the same as sent in querySR response.|
|12||publishLOV||Publishes a pre-defined list of values (LOV) for various keys for Client Support CRM system to use for composing API requests.|
|13||getLOV||As an alternative to creating an endpoint and receiving publishLOV messages sent by Juniper on a periodic basis, the getlov API can be used to fetch the applicable List of Values (LOV) for various keys for Client application to use for composing API requests and understanding the various LOVs for some keys in API responses.|
publishSR Process (Push Notifications)
Clients must provide a secure endpoint for Juniper to post messages. You can receive real-time notifications of changes to your SRs, so you don’t have to track your open SRs and frequently do a querySR. This helps avoid reaching your rate limit. This is our publish/subscribe model, which is same as a push notification model.
On SR changes, push notifications are immediately sent to your secure endpoint which contain a JSON payload of the SR (with all SR details). You can update the corresponding ticket on your CRM support system right from the notification.
On a periodic basis Juniper will also publish the pre-defined list of values (LOV) (publishLOV) for various keys for Client application to use for composing API requests.
publishSRs (SR push notifications) and publishLOV are sent over HTTPS to your secure endpoint. Juniper can authenticate with your secure endpoint using certificate-based authentication or any standard authentication mechanisms, except username and password.
The architecture supports clients with one crm system and one endpoint or mulitple crm systems and one end point or multiple crm systems with multiple end points. The payload always includes the Customer Source Identifier, Customer Case Number, and SR details.
PublishSR illustration - Client with One CRM system and One Secure Endpoint
PublishSR illustration - Client with Multiple CRM system and One Secure Endpoint
PublishSR illustration - Client with Multiple CRM system and Multiple Secure Endpoints
Supported API Authentication Mechanisms
Clients can choose from three authentication mechanisms for connecting to Juniper: OpenID Connect (OIDC), OAuth2.0 and Certificate based. All services are RESTful and invoked over HTTPS.
OIDC (OpenID Connect) Authentication Mechanism
For Clients who have already deployed OIDC within their organization, OIDC would be the preferred choice of authentication mechanism to connect to Juniper CaseAPIs. Clients who choose this authentication mechanism need to provide Juniper an ID token as part of the Onboarding process.
A good reference describing OpenID Connect can be found here.
OAuth2.0 Authentication Mechanism
Juniper CaseAPIs support the popular OAuth2.0 Authorization protocol. Juniper provides a clientid, secret and a token endpoint. Token endpoint is used to obtain an access token by presenting clientid, secret. Each API request is made with header containing the access token information. Juniper will rotate the secret yearly to enforce enhanced security.
A good reference describing OAuth2.0 can be found here.
Certificate-based Authentication Mechanism
Juniper CaseAPIs support Mutual SSL authentication or certificate based mutual authentication. Clients choosing this method for authentication need to create a X509 public/private key pair and share the CA signed public certificate with Juniper. Certificate is to be presented during the SSL handshake on each API request. Client needs to provide Juniper with a new CA signed public certificate prior to expiry of the current certificate.
A good reference describing Certificate based (aka MTLS - Mutual SSL authentication) can be found here.
Authentication and Authorization Aspects on API Requests
The request follows these authentication steps:
- Trusted Channel: Received with valid encrypted signature over HTTPS (TLS1.2+).
- Rate Control: The Client must be within the rate limits.
The request follows these authorization steps:
- API Key (appId): is a valid API Key in the Request header as established during the onboarding process.
- User Authentication (userId): userId is a registered user established during the onboarding process.
- Account (accountId): is a valid account identifier as established during the onboarding process.
- Contact Email (contactEmail): is a valid registered user identifier associated with the account.
- On createSR this user becomes the SR Reporter.
- On updateSR this user is recorded as the originator of the update.
- Service Request (serviceRequestNumber): is associated to the account.
Attaching Files to an SR
Through the API channel, you can upload files to Juniper’s AWS S3 storage space using a three-step process:
- Request a token (getfileUploadToken). Response contains stsToken information.
- Use the stsToken and any of the AWS S3 SDKs to upload the file to Juniper’s AWS S3 storage area. You can upload mulitple files using one stsToken. Note: The S3 call must include the required metadata.
- After a successful file(s) upload to AWS S3, call the attachFile API and provide the file details (filename and AWS filename and document path). A link to the file is created in the SR so that JTAC engineers can view the file(s) and the file(s) is also accessible via other channels, such as the Casemanager and MyJuniper portals.
Note: All files reside on Juniper's AWS S3 storage area.
AWS S3 SDK References
- For information on using the AWS S3 SDK and testing your Java code examples, see the Amazon document on Using the AWS SDK for Java.
- For information on using the AWS S3 SDK to get the authentication token, see the Amazon documentation on Making Requests Using IAM User Temporary Credentials - AWS SDK for Java.
API Versioning and Juniper Endpoints
Each Case API maintains a version. Juniper supports the current and previous versions of the APIs. When it is not possible to maintain a version, Juniper will notify Clients.
All APIs are protected. After the onboarding process, Juniper will send you the API URLs.
Open Source Components
The Case API uses the following Open Source Software:
|Open Source Component||License|
|Tyk Gateway (tyk-gateway)||Mozilla Public License 2.0 https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md|
Interested? What's Next?
If you are interested in the Juniper Case API model and capability for a B2B integration with the Juniper Support CRM system please review the Onboarding Process to get started. It is simple! Complete this Onboarding Request Form.