Getting started

• Prerequisites

• Contracting with Orange Business Services

• Specifying your operating mode

• Project phases

• Publish and subscribe to the APIs

• Consume the APIs

• Development phase

• Integration phase

• Development and integration overheads

• API description

• Overview

• Summary of resources

• Summary of methods and URL

• POST /productordering/v2/productOrder

• POST /[offer]/productordering/v2/event

• GET /userservice/v2/userService

• POST /userservice/v2/userService/update

• POST /[offer]/userservice/v2/event

• Advanced description

• Glossary

• History of document

Prerequisites

Contracting with Orange Business Services

Before implementing the API, a partnership agreement must be established between your company and the Orange team responsible for Business Apps partnerships.

Your Orange contact: businessapps.contact@orange.com.

Once the partnership agreement is established, you will receive a contract number which will be required when subscribing to the Orange Business Applications offer.

The agreement itself will include useful information such as:

• A list of Orange contacts for the integration and production phases.

• Additional information about API use (mentioned in the Appendix 2 of the contract, "Technical specifications of APIs").

The Appendix 2 will allow each partner to specify the features of userService they want or can implement.

Specifying your operating mode

The minimum features required to be displayed by an Orange Business Applications partner are identified inside the following array.

Specify whether the results will be provided in synchronous or asynchronous mode.

In the Appendix 2, you must in particularly :

• Define the technical information required to deliver the service and specify if this technical information is only technical a prerequisite or if it should be provided in addition to the subscribed offer to properly configure the licenses (example: storage size, CPU value, OS type and version ...). A technical resource has a generic name (name) and one or more properties (value).
• Optional: Define the type of medium (Type of RealizingResource) on which the licenses are running to deliver the service to the end user. Typical examples of Realizing resource are an URL (access to the service via a URL), an email, a phone number, IMEI, etc. In the APIs, the value of this item is called RealizingResource).

For any question about Business apps features to provide inside Appendix 2 of the agreement , contact us at the following e-mail address : Orange business Applications technical team

Go Up

Project phases

Publish and subscribe to the APIs

At least two weeks before the integration phase, you have to publish the APIs (ProductOrdering and UserService).

To achieve this, the different steps are as follows:

1. Create an account on the current Orange Partner site
2. Log on and create your application: you get credentials you may use to obtain an access token (OAuth 2.0) and be able to invoke Orange Business Applications API events.
3. Subscribe to Orange Business Applications APIs (select Orange Business Applications in the list of APIs to include in your application). Orange team will validate your subscription to activate authentication key for your API subscription
4. As soon as API is included in your application (don't wait for API validation, click right now), click on "configure" button to fill a form with the contract number and technical informations used by Orange to call your API.

Those steps are detailed through the following screenshots: screenshots.

Nota: This section describes how to subscribe to APIs in the Orange production environment. To test the APIs during integration phase in a non-production environment, you have to subscribe to a specific offer "Orange Business Applications – Beta". You must contact the Orange technical team at the following e-mail address Orange business Applications technical team to manage this subscription. They will help you to to receive an invitation to subscribe.

Consume the APIs

The standard protocol of authentication OAuth 2.0 with https is used with grant_type = client_credentials to manage the authentication of an application to access resources through Orange Partner Gateway (See here for more information about 2-Legged OAuth2.0 proxy V3 identity and authentication protocol):

The following document explains how to request a token via the server token provided by the Orange Gateway OPE and how to use this token to consume the API toward the Orange gateway OPE: Consumption of an API via Orange Gateway OPE

Development phase

JSON files are provided to assist you in the development phase in the following zip files: productOrder zip file and userService zip file

A dedicated API must be reserved for web application server status. This API must be named "ping", available as a GET request, and the response must be HTTP 200.

During the development phase, in addition to the tests performed in the partner IT, developers could use a tool provided by Orange: Partner Onboarding Helper. This application allows to perform in complete autonomy a first level of tests on the development done to integrate part of functionalities of the Orange Business Applications France API. it allows to simulate the API calls made in synchronous mode by the Orange IT without asking Orange to make these calls. The aim is to check that the data provided in the response is consistent with what Orange SI expects. To obtain the installation procedure and a user guide for this application, send an email at shine2.onboarding@orange.com.

Integration phase

Once your APIs are developed, tested and published, you will start a new phase: the integration tests.

Because, during this integration phase, the API calls are initiated by Orange, you must send an email at shine2.onboarding@orange.com to begin testing.

The integration phase is divided in two steps :

• Step1: tests on a non-production environment on Orange side. All the use cases implemented are tested to validate the APIs developments done by the partner and to validate the use of the event implemented by Orange if the partner manages asynchronous response. On the partner side, we recommend performing the tests in a development environment.
• Step2: once all the tests performed during step1 are OK, tests are now performed on the production environment on Orange side using a simulated customer. Only some functional tests are performed to verify that all is OK.

After the validation tests have been completed, the operational phase may start as defined in the joint agreement (between your company and Orange). The prerequisite is to publish your APIs to your production environment (cf. Publish and subscribe to the APIs as it can require to create an application again if you first create an application for your development environment)

Development and integration overheads

Here are some questions to help you estimate the cost of the integration project:

• Did I already expose APIs to partners or customers ?
• Am I familiar with web service REST style ?
• Are the concepts used in API already implemented into my information system ?
• Is the data model exchanged via APIs distant or close to my model ?
• How many features need to be implement ?
• Will results of operations sent by APIs be provided synchronously or asynchronously (asynchronously you must invoke the event resource to send the result so there are additional development on your side) ?

To give you an idea, the average is about 15 man-day to integrate the two APIs.

Go Up

API Description

Overview

To interact with partners and provide a seamless customer experience, Orange provides partners with a set of API enabling orders and change management.

The set of APIs is called Orange Business Applications API

These APIs are developed both by Orange and our partners.

Thanks to the APIs:

• partners receive customer requests to apply in their system (orders or changes on existing application)
• partners can answer in a synchronous way or can update Orange later when the deployment of orders is terminated and/or changes done.

Synchronously, the partner immediately processes the request and returns the corresponding response. Asynchronously, the partner registers the request which is subsequently processed and returns an acknowledgment. Once the request is processed, the partner sends Orange the response, calling the event resource (see explanation in next chapters).

Two APIs are used:

• ProductOrdering for customer creation, first order to activate services or adding of services in one existing fleet.

• UserService for service management (consult, change status, change offer, manage end user, delete license, renew login or change technical support of license). Notice that renew login, manage end user and change technical support of license is not done from Orange request, these operations are sent by partner to Orange, these operations are never sent by Orange to partner.

Inside each API, there are 2 main resources:

• the main business resources exposed by partner and consumed by Orange (allowing Orange to transfer customer requests to the partner):
  • productOrder inside ProductOrdering API,
  • userService inside UserService API,
• the event resource exposed by Orange and consumed by partner. This resource is provided both inside ProductOrdering and UserService APIs. It allows the partner to answer Orange requests in an asynchronous way.

The following illustration shows what is under the partner's responsibility in term of development:

The UserService API allows to manage several type of changes. It can be implemented partially by the partner. The list of operations chosen by the partner has to be provided during the initial partnership discussion phase (see chapter "before starting" for information to provide in the agreement).

Go Up

Standard sequence of activities relying on the API bundle

Nota: As the integration phase is performed on an Orange non-production environment and then on an Orange production environment, two offers are necessary. So, in the API call mentioned in the following table, the variable [offer] is valued at “mba2” for production or at mba2-beta (for beta version). This variable is only necessary in the case of the use of the event by the partner to manage an asynchronous response. During the integration/phase, the same sequence of activities described in the following table is done as in deployment phase but on a limited number of user services.

(*1) Partner may implement a synchronous or an asynchronous response to orange POST requests

Go Up

Summary of resources

The main resources of the two APIs and the relationships between the 2 models'ID are represented in the following diagram.

Cross- references The ExternalReference resource represents Orange references of different resources whose ID attribute is generated by the partner's IT. The diagram does not present all resources which have an ExternalReference.

ProductOrdering API

UserService API

Go Up

Summary of methods and URL

ProductOrdering API

Nota: [offer] = mba2 (for production) or mba2-beta (for beta version)

UserService API

Nota: [offer] = mba2 (for production) or mba2-beta (for beta version)

Go Up

POST /productOrder

POST /productordering/v2/productOrder

• Request body resource : productOrder
• Response body resource : productOrder

The value of productOrder.state provided in the HTTP POST response allows to distinguish how the partner will answer:

• value is acknowledged if asynchronous response is provided,
• value is completed or failed if synchronous response is provided.

Note: The order request contains only one order item.

UC1 - Partner creates the customer and contacts

Orange sends the partner a productOrder with the customer, customer contacts and Orange contacts, but with no orderItem nor endUserConfiguration.

No product or service is created. Only customer and contacts are created.

UC2 - Partner creates the customer fleet and activates user services

Orange sends a productOrder to the partner with add action on orderItem. The category attribute of the productOrder is valued to 'production'. For each orderItem the externalReference of a product offering and an userServiceQuantity are provided to create the product. endUserConfiguration may also be provided in the orderItem depending on what was precised inside Annex 2 of the contract.

In a synchronous or asynchronous mode (see also UC4), the fleet with its licenses is created by the partner and the fleet ID (productRefId) is generated. The fleet ID returned to Orange in the final response will be used to get licenses using the UserService API for one dedicated customer and for next orders.

The partner creates the fleet and associated services for the customer.

In synchronous mode, the value of productOrder.state returned can be:

• completed if all end user services are produced (not used),
• failed if nothing has been produced.

In asynchronous mode, the value of productOrder.state returned synchronously is acknowledged if no error occurred. Then, asynchronously, the POST /event sends the value of the final state: completed or failed.

Notes:

• The order request contains only one order item.
• The licenses are created and returned with a GET only when the product order state is valued to "completed'.

UC3 - Customer adds new licenses

Same behavior as in UC2 except that the fleet id is provided by Orange (this is the fleet id collected at first order. Reminder: fleet id = productRefId

Orange sends a productOrder to the partner with order items each refering to a previously created product by its productRefId. A complementary userServiceQuantity is given.

The partner may choose to create a new productRefId or not for the added services. The rule is: the productRefId (ID of the customer fleet) known by Orange is used in the request and:

• If possible, the new created licenses are attached to this fleet ID.
• Otherwise, the new licenses are attached to another fleet ID (either new or existing) and in this case, the partner provides this fleet ID in the answer.

Go Up

POST /event on productOrder

POST /[offer]/productordering/v2/event with [offer] = mba2 (for production) or mba2-beta (for beta version)

• Request body resource: event
• Response body resource: event

UC4 - if the partner has implemented asynchronous response, the partner sends Orange response for UC2 and UC3

If partner has implemented asynchronous response for Orange requests, the value of productOrder.state in HTTP POST response is acknowledged. Then, the partner sends an event with the final value of productOrder.state and content.

The event has a state according to the value of the order final state: completedStateNotification or failedStateNotification.

Note: in this release, the order request contains only one order item.

The event provides the details of the productOrder with created or modified resources especially productRefId or id of userService and the state of the productOrder and product order items.

Go Up

GET userService

GET /userservice

• Request query parameter:

• id (a list of userService IDs, comma separated)

• or path parameter: userService/{id} (to consult one service)

• or productRefId (id of the fleet of user services)

• Response body resource: array of userService corresponding to the parameter given in the request

UC1 - Orange consults licenses

The query parameters allow three kinds of consultations:

• get all user services for one given customer fleet. Note that if the partner creates a new fleet (new producRefId) each time user services are added, then many calls may be necessary to get all expected user services,
• get a list of user services using their IDs,
• get one dedicated user service.

Nota: Only consultation with a fleet identifier (productRefId) is implemented.

Go Up

POST userService/update

POST /userservice/v2/userService/update

• Request body resource userServiceUpdate
• Response body resource : userServiceUpdate (contents state attribute and an array of userServices)

The value of state attribute of userServiceUpdate is acknowledged if the response is asynchronous, completed or failed if the response is synchronous and no error.

Note: The global response must be completed or failed. All requests for changes (array of user services) are managed as a transaction.

UC2 - Orange suspends or reactivates licenses

If Orange sends a list of licenses with the value of userService.externalState equals to suspended or inactive then the partner inactivates the userService and set the value of userService.state to inactive.

The inactivation does not suppress the user service nor modify their login or password.

If the value of userService.externalState is equal to active then the partner reactivates the userService and the value of userService.state is changed to active.

UC3 - Orange deletes licenses within one customer fleet

If Orange sends a list of user services with a value of userService.externalState equal to deleted then the partner terminates the corresponding userService.

UC4 - Orange manages change on licenses: product offering migration

Orange sends the partner a list of user services with a productOfferingOperation.

A productOfferingOperation consists of the swap action of the productOffering. The externalReference of the new productOffering is supplied by Orange.

Go Up

POST /event on userService

POST /[offer]/userService/v2/event with [offer] = mba2 (for production) or mba2-beta (for beta version)

• Request body resource: event
• Response body resource: event

UC5 - Partner manages change on licenses through operations on the end user, on the login/password and on technical resources

These operations are sent by Partner to Orange using event of UserService API. The partner sends Orange a list of user services with a list of operations for each.

UC5.1 - Manage the end user of a user service

An endUserOperation consists of an action on enduser data:

• action = add to link the service to a user if no user was already linked
  • user data is provided (name, email,...)
  • user ID is generated by the partner except if Orange provides one that was previously generated by the partner and that still exists.
• action = modify when an existing end user linked to a license is updated (change of name, email for ex)
• action = delete when an end user is deleted from an existing userService (then no more end user is specified)

UC5.2 - Manage the technical resources of a user service

A realizingResourceOperation consists of change on technical resource:

• action = modify to initialize or update the realizingResource.
  • the type of support on which the licenses are implemented to deliver the end user service is provided (mobile, URL, email, etc).
  • the values of realizing resource properties defined by partner are provided.

UC5.3 - Manage the login of a user service

A RightOperation consists of change on login information

• a login type (LoginKeyValue.key): either login if specific or organizationCode if common to all user services
• a login value (LoginKeyValue.value)
• an e-mail to send the login and/or password

UC6 - if partner has implemented asynchronous response, partner sends response to Orange for UC1 and UC2

The event has a state updateNotification and contents an array of userServices.

The value of userServiceUpdate.state in the HTTP POST response allows to distinguish how the partner will anwer: acknowledged if asynchronous response, completed or partial or failed if synchronous response.

Note: the partial state is not used. The global response must be complete or failed. All requests for changes (array of user services) are managed as a transaction.

Go Up

Advanced description of the API

The "getting advanced (PDF)" document details the different use cases with sequence diagrams and examples : Advanced description of API

Go Up

Glossary

Go Up

History of document