Predictive Inventory Management Service

The Predictive Inventory Management Service enables API callers to generate stock replenishment proposals based on historical data which includes supplier orders and customer orders.

Access info

Usage

Prerequisites

• The organization(s) for which reporting is done must exist in the SBS system. You can add new organizations either from the Organizations UI or programmatically from the Organizations Service.
• The following CSV files are required as input to te Predictive Inventory Management service (click the links below for information about the structure of the file):
  1. CustomerOrders.csv
  2. SupplierOrders.csv

Generating a replenishment proposal

To generate a replenishment proposal:

1. Obtain from your ERP system the input CSV files to be used as input. For the structure of each file, see Appendix 1: Input structure.
2. Create a new replenishment proposal by calling the createReplenishmentProposal mutation. You must supply as input argument, at the minimum, the target month, in the format YYYY-MM. As a result, a new replenishment proposal object is created, and the response contains the unique proposal ID. You will need to work with this ID in subsequent steps to further process the proposal and monitor its status.
3. Add all the input CSV files to the proposal. See Preparing input files.
4. Run the computeReplenishmentProposal mutation. This triggers a computation that takes place from several minutes to several hours, depending on the size of input CSV files.

The outcome of computing a proposal, including any possible errors, is reported in the Process object when querying the respective proposal. If the computation was successful, the process includes one or more of the following attributes:

• productCentricResult - This is the default result and it is always present. It contains, among other attributes, the name and download URL of the output file, with computation results grouped by product. For the structure of the output file, see Appendix 2: Output structure.
• customerCentricResult - This result is present if the proposal was created with the input parameter splitByCustomer = true. The result has the same structure as above, except that data inside the output file are grouped by customer.
• industryCentricResult - This result is present if the proposal was created with the input parameter splitByIndustry = true. The result has the same structure as above, except that data inside the output file are grouped by industry code.

Preparing input files

After you have create a replenishment proposal, you can add all the CSV input files to it.

For each input CSV file, the steps are as follows:

1. Run the prepareFile mutation, for example:

mutation prepareFile($replenishmentProposalId:ID!, $input:PrepareFileInput!) {
  prepareFile(replenishmentProposalId:$replenishmentProposalId, input:$input) {
    id
    fileType
    name
    contentLength
    uploadUrl
    downloadUrl
    createdAt
  }
}

{
    "replenishmentProposalId": "YOUR_REPLENISHMENT_PROPOSAL_ID",
    "input": {
        "fileType": "CustomerOrders",
        "name": "customer-orders.csv"
    }
}

In the response, you get the file’s upload URL at which you can upload the actual file.

2. In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL. This step is similar to how you would create a file and then upload its content in the File Management Service, as described in the Tutorial: Create a file.

Note that you can add multiple files of the same type for the same replenishment proposal. For example, you can add several input CSV files of type “CustomerOrders”. If multiple files of the same type exist, SBS will aggregate and compute data found in all respective files.

After adding all the CSV files, you can check if they are indeed attached to the replenishment proposal by running the replenishmentProposal query, for example:

query ReplenishmentProposal ($id:ID! $fileId:ID, $processId:ID) {
  replenishmentProposal(id:$id) {
    id
    organizationId
    files(id: $fileId) {
        id fileType name contentLength uploadUrl downloadUrl createdAt
    }
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

If your replenishment proposal looks good so far, you can proceed to running the computeReplenishmentProposal mutation, for example:

mutation ComputeReplenishmentProposal ($id:ID!) {
  computeReplenishmentProposal(id:$id) {
    id 
    status
    dataRange { from to } 
    targetMonth
    errorMessages
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

Dealing with large input files

As mentioned above, when you add a file to the replenishment proposal, there are two steps involved:

1. Run prepareFile and obtain the upload URL.
2. In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL.

For the second step, note, however, that the maximum file size that you can send in a single PUT request is 5 GB. Should you need to add larger files to the replenishment proposal, you can do so through the multipart upload mutations provided by the File Management Service. In this scenario, the process looks as follows:

1. Run prepareFile and take notice the data.prepareFile.id returned in the response body. This ID corresponds to a file id of a file in File Management Service.
2. Provide the id above as input to the initiateMultipartUpload mutation and continue with the rest of steps required for multipart upload, as described in Uploading large files.

Processes

Each time when you run computeReplenishmentProposal, a new process with status NEW is attached to the replenishment proposal. You can view the proposal and the status of all its processes by running the replenishmentProposal query and requesting the processes field in the response, for example:

query ReplenishmentProposal ($id:ID! $fileId:ID, $processId:ID) {
  replenishmentProposal(id:$id) {
    id
    organizationId
    targetMonth
    splitByCustomer
    splitByIndustry
    files (id: $fileId) {
        id fileType name contentLength uploadUrl downloadUrl createdAt
    }
    processes (id: $processId) { 
        id 
        status
        dataRange { from to } 
        targetMonth
        errorMessages 
        productCentricResult { id name contentLength createdAt downloadUrl }
        customerCentricResult { id name contentLength createdAt downloadUrl }
        industryCentricResult { id name contentLength createdAt downloadUrl }
        totals {
           csvLines { customerOrders supplierOrders allFileLines }
        }
        createdAt
    }
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

The status of any process is initially NEW. The status NEW will normally change to INPROCESS after approximately 1 minute. Note that, if you run computeReplenishmentProposal multiple times for the same proposal, each run will start a new process. In this case, you will need to track the status of each process separately. The processes field of the replenishmentProposal query provides a filter (by process ID) for that purpose.

The INPROCESS status of a process may take from a few minutes to a few hours, depending on the size of the input CSV files. After the INPROCESS status, the status may change to either ERROR (if errors are encountered) or DONE (upon successful processing).

If the status ERROR is encountered, check the errorMessages response field of the respective process for details.

If the process completes with status DONE, it generates 1-3 CSV output files. As mentioned previously, the number of files depends on the input parameters supplied at proposal creation time to the createReplenishmentProposal mutation.

If necessary, you may stop a running process through a call to killProcess. However, this is possible only if the process has not generated any results (that is, if the result field of the process is empty).

You may also delete a process through the deleteProcess mutation. Deleting a running process is possible only if the process has generated no result yet.

Deleting replenishment proposals

You can delete replenishment proposals through a call to deleteReplenishmentProposal. Note, however, that it is not possible to delete a replenishment proposal if it has at least one running process that has already generated some result file. To delete such a proposal, you will need to wait for the process to finish first.

Queries

organizations

Returns a list of active organizations defined for the given tenant.

Result

The result is an array of Organization.

Organization type

replenishmentProposals

Returns the list of replenishment proposals for the organization ID supplied as input.

Arguments

ReplenishmentProposalsFilter input

DateFilter input

Result

The result is an array of objects of type ReplenishmentProposal.

replenishmentProposal

Retrieves a single replenishment proposal by ID.

Arguments

Result

See the ReplenishmentProposal type.

Mutations

computeReplenishmentProposal

Starts a process that computes a replenishment proposal, based on its current input data. Running this mutation will start a new process on each run.

Arguments

Result

See the Process type.

createReplenishmentProposal

Creates a replenishment proposal.

Arguments

CreateReplenishmentProposalInput input

Result

ReplenishmentProposal type

File type

Process type

DataRange type

ResultFile type

Totals type

CsvFileLines type

deleteFile

Deletes a previously uploaded CSV file.

Arguments

Result

DeletedFile type

deleteProcess

Deletes a computation process and the result files.

Arguments

Result

See the Process type.

deleteReplenishmentProposal

Deletes a replenishment proposal, including all its input and output files and processes.

Arguments

Result

See the ReplenishmentProposal type.

killProcess

Stops a running computation process.

Arguments

Result

See the Process type.

prepareFile

Generates a URL at which you can upload a CSV file to be used as input to the computation. Run this mutation for each CSV file that is to be supplied as input for a replenishment proposal.

Arguments

PrepareFileInput input

Result

See the File type.

Appendix 1: Input structure

The input to the Predictive Inventory Management Service consists of two CSV files:

1. CustomerOrders.csv
2. SupplierOrders.csv

You may supply multiple files of the same type as input as long as they follow the structure described below. Note the following:

• Each CSV file is comma-separated
• The first row in the CSV file should provide the column names (that is, the CSV file must include the header).

CustomerOrders.csv

SupplierOrders.csv

Appendix 2: Output structure

The result of computing a replenishment proposal is a CSV file having the structure described below.