REST API for Element Manager in B2C Service

Quick Start

You can use Oracle B2C Service Element Manager REST APIs to migrate resources across B2C Service instances. You can easily make requests to create, export, search, download, import, or rollback Element Manager packages. An Element Manager package can contain resources of type Report, Workspace, CustomObject and so on. But, let's first send a simple REST HTTP request to get the status of exported Element Manager packages.

Step 1: Consider Before You Start

Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON, and scan our list of important terms.

Review Roles and Privileges. You must have the necessary security roles and privileges to use the GET, POST, PATCH, and DELETE methods on your parent and child resources.

Review opt-in requirements. Some resources or their attributes may be associated with features that require opt-in before you can use them. You must make sure that you enable opt-in features before you start.

Choose a REST client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But, cURL isn't the only tool you can use. To help you choose one, see Work with your REST Client.

Note:

You can integrate with Oracle B2C Service Element Manager REST APIs through custom client applications developed using languages such as Java, JavaScript, Ruby, and so on.

Do NOT use the swagger.json available on Oracle Help Center to develop integration code for Oracle B2C Service Element Manager REST APIs. This swagger.json is a sample created solely for documentation purposes and does not fully express the capabilities of the Oracle B2C Service Element Manager REST APIs.

Step 2: Get Your Oracle B2C Service Account Info

To make a REST HTTP request, you need to gather a few bits of information:

REST Server URL. Typically, this is the URL of your Oracle B2C Service server. For example:
```
https://mysite.example.com
```
User name and password. An Oracle B2C Service user with permissions to access the REST resources you're using.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle B2C Service administrator.

Step 3: Configure Your Client

With the information gathered so far, you're ready to configure your client to send a REST HTTP request.

Construct the request URL. The URL consists of the server name and the resource path:
```
https://<server>/<resource-path>
```
The <server> is the REST Server URL from Step 2, as in:
```
https://mysite.example.com
```
The <resource-path> is the relative path or endpoint to the resource you're working with. You can pick any endpoint in All REST Endpoints. For example, we're interested in getting the status of exported Element Manager packages:
```
/AgentWeb/api/elementmanager/export/EMPackages
```
Combine the REST Server URL and, in this example, the resource path and your request URL is complete. For more information, see URL Path.
```
https://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages
```
Set the custom headers. You must include the following customer headers in your requests:
- API_VERSION: The API version for the header. The default value is 1.
- USERSESSION: The authentication token for the header. See Step 4 for details.
Include the custom headers using the -H command as follows:
```
-H "API_VERSION: 1" -H "USERSESSION: feihg98GnT7i"
```

When you're done, the complete cURL command should look like this:

curl -X GET https://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages -H "API_VERSION: 1" -H "USERSESSION: feihg98GnT7i" -H "Content-Type: application/json"

If you're not familiar with any of the syntax used in the example, check out Work with your REST Client.

Step 4: Authenticate and Authorize

Now that you've configured the client with a complete request URL, it's time to authenticate and authorize yourself. Authentication proves that your credentials are genuine, and authorization allows you to apply your access privileges.

Authentication

To make sure data access over a network is secure, you must pass an authentication token in the USERSESSION header when you access a REST API operation.

You must use one of the following operations to obtain an authentication token:

Get an authentication token (for release 19A and lower), if you are fetching an authentication token for sites 19A and lower.
Get an authentication token (for release 19B and higher), if you are fetching an authentication token for sites 19B and higher.

Let's look at an example for obtaining an authentication token for sites 19A and lower. To obtain an authentication token, you must submit the user name, password, and REST server interface URL for your Oracle B2C Service site, using the following cURL command:

curl -X POST https://mysite.example.com/AgentWeb/api/securityservice/authentication/authToken -H "Content-Type: application/json" -d "{ \"username\": \"MyUser123\", "password": \"MyPwd123\", \"interfaceUrl\": \"https://mysite.example.com/myinterface.cfg\" }"

This is how the request looks in Postman:

Example of authentication token request in Postman.

If your request is successful, you receive a token in the response with a body similar to the following example. The token in the following example has been abbreviated for readability.

{
    "description": "Authorization token",
    "token": "feihg98GnT7i"
}

You can now access the REST APIs by passing the authentication token in the USERSESSION header in your requests.

Step 5: Send an HTTP Request

You're almost done. Now that your authentication and authorization are set, you're ready to send a test HTTP request. Continuing with our example, we want to get the status of exported Element Manager packages. You can do this using the following command in cURL:

curl -X GET https://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages -H "API_VERSION: 1" -H "USERSESSION: feihg98GnT7i" -H "Content-Type: application/json"

This is how the request looks in Postman:

If your request for information about the account object is successful, you receive a response with a body similar to the following abbreviated example. If your request fails, and you're using cURL, review the response comments, adjust your request, and then try again. If you're using other clients, review the failure Status Codes, and then try again.

{
    "description": "Collection of packages",
    "items": [
        {
            "id": 100014,
            "name": "Test three",
            "status": {
                "code": "3",
                "description": "Export prepare complete"
            },
            "href": "http://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages/100014"
        },
        {
            "id": 100013,
            "name": "Test two,
            "status": {
                "code": "5",
                "description": "Export complete"
            },
            "href": "http://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages/100013"
        },
        {
            "id": 100001,
            "name": "test one",
            "status": {
                "code": "3",
                "description": "Export prepare complete"
            },
            "href": "http://mysite.example.com/AgentWeb/api/elementmanager/export/EMPackages/100001"
        }
    ]
}

Congratulations! Now you're ready to do more with your REST APIs.

Learn about common processes in the Use Cases section, such as how to create an export package, import a package, and rollback a package.
Explore the Learn More section.
Join the Oracle Developer Community, where you can share tips and advice with others.