Build Product Operation

Build Product

The Build Product operation takes the configured product based on a product service definitions and recreates a functional equivalent of that product based on (product) benefit specifications.

Not all products are eligible for being processed. For example, products in the status Approved, Review, or Test are not eligible. A Product’s built eligibility is derived from the presence or absence of the Build link.

Resource Representation

Resource representation of a product that can be built:

{
  ...  product properties ...
  "links": [
    {
      "href": "http://<host>:<port>/api/generic/products/{id}",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/products/{id}/build",
      "rel": " product:build"
      "httpMethod": "POST"
    }
  ]
}

In the resource representation of a product that cannot be built, the build link is not provided:

{
  ...  product properties ...
  "links": [
    {
      "href": "http://<host>:<port>/api/generic/products/{id}",
      "rel": "self"
    }
  ]
}

Build Process

Using this operation the user can build the product. During the build process the following steps are performed:

  • Validate the product

  • Generate Benefit Specification

  • Generate Product Details

  • Change Product status to Review

  • Update Product Status History

  • Increment the build number of the product

For more details, see Build Product under Operations Guide.

In regard to building a product, three use cases can be distinguished:

  • Use Case 1: The product is in the status Edit, where manual changes are possible. Building the product will bring it to the next status i.e., Review

  • Use Case 2: The product is being processed/triggered build with the status Queued. Building the product is not possible in this case. There is an additional link to the buildstatus resource which clients can use to monitor the process or analyze the last error.

  • Use Case 3: The product is already built and is ready to be Tested or Approved. Re-building the product is not possible at this state. Example: Product in status Test.

The following table gives an overview of the build eligibility of the product:

Table 1. Build Process
Status Eligible for Build Link Build Status Resource Available

Approved

No

No

Edit

Yes

Yes

Queued

No

Yes

Review

No

Yes

Test

No

No

When a product cannot be built, the system returns the following error:

Table 2. Error Message
Code Severity Message Text

PRD-HTTP-001

Fatal

Product must be in status edit to start the "build" process

When a product is currently being processed, or the last processing did not end in a valid end status, a build status link is included:

{
  ... product properties ...
  "links": [
     {
      "href": "http://<host>:<port>/api/generic/products/{id}",
      "rel": "self"
    },
     {
      "href": "http://<host>:<port>/api/products/{id}/buildStatus",
      "rel": "product:buildstatus",
      "httpMethod": "GET"
    }
  ]
}

API Conversation and Interaction

The API conversational and interaction style is based on its asynchronous nature. The client of this API will become detached from the actual background process. The client can use the buildstatus resource to monitor that background process. So the API client is not blocked but is provided with the means to track progress asynchronously.

After this process, this means that product has been built or there were errors during processing. Both of these outcomes are made available/accessible for the consumer of this API.

Resources used in this API

Product Resource

A product resource is a singular resource representing a product. For more details about the representation, see Default Resource Representation (GET). The product resource contains the Build link or the link to the status resource.

Build Status Resource

These resources provide the basic elements with which building a product can be fulfilled - including tracking progress, and the ability to show processing errors.

As these are individual states of the application that allow a consumer to converse with the system.

Link Relations used in this API

In the case of building a product for processing, the following link relations are defined.

  • rel="product:build"

To eventually have a product in the context of this link relation - processed by the system.

  • rel="product:buildstatus"

To request the status of the current or last product build action.

  • rel="self"

Link to the current resource. For instance, this can be used on the status resource to poll the resource for progress tracking periodically.

  • rel="related"

This is a standard link relation to the related (product) resource. This should be provided once the request is completed successfully.

Using the IP to Build a Product

The Product is in a status Edit, i.e., the build process can be started.

Interaction Messages

The client requests a product. The product is returned like this:

{
  ... Product properties ...
  "links": [
    {
      "href": "http://<host>:<port>/generic/products/{id}",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/products/{id}/build",
      "rel": "product:build",
      "httpMethod": "POST"
    }
  ]
}

The client initiates the build process for the product by calling POST on "api-context-root/products/{id}/build".

The product processing is started, and the server responds with status 201 (Created).

A link to the buildstatus resource is returned in the response header like: Location: api-context-root/product/{id}/buildstatus

The clients can now track the progress by issuing a GET to the status URI returned in the response header. While the product is being processed, the status resource will be returned like:

{
    "progress": "processing",
    "links": [
    {
      "href": "http://<host>:<port>/generic/products/{id}/buildstatus",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/products/{id}/",
      "rel": "related"
    }
  ]
}

When the processing ends successfully (no errors), the status resource will return:

{
    "progress": "succeeded",
    "links": [
    {
      "href": "http:http://<host>:<port>/generic/products/{id}/buildstatus",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/products/{id}/",
      "rel": "related"
    }
  ]
}

When the processing ends unsuccessfully, the status resource returns:

{
    "progress": "failed",
    "o:errorDetails": [
    {
      "detail": "<detailed message 1>",
      "o:errorCode": ""
    },
    {
      "detail": "<detailed message 2>",
      "o:errorCode": ""
    }
  ],
    "links": [
     {
      "href": "http://<host>:<port>/generic/products/{id}/buildstatus",
      "rel": "self"
     },
     {
      "href": "http://<host>:<port>/products/{id}/",
      "rel": "related"
     }
  ]
}

If the build process has not been initiated for a new product, the status resource returns:

{
    "progress": "notStarted",
    "links": [
    {
      "href": "http://<host>:<port>/products/{id}/buildstatus",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/generic/products/{id}/",
      "rel": "related"
    }
  ]
}

Response Messages

This operation provides HTTP status codes as defined in Response Messages.

If an error occurs, the appropriate HTTP status code is returned.

The following operation specific error can occur:

Code Severity Message Text

PRD-HTTP-001

Fatal

Product must be in status edit to start the "build" process

Authorization

The Build Product operation is protected by access restriction product.build IP.