Sourcing Event Creation From Template
The Create Sourcing Event from Template API enables the creation of Sourcing Events while allowing existing Sourcing Events or Event Templates to act as a template for new jobs.
The request payload for the /jobs/create-sourcing-events endpoint allows full flexibility when creating
your sourcing event, but can result in large complex payloads in advanced use-cases. The
/jobs/create-sourcing-events-from-template eases this burden by allowing the use of an existing Sourcing
Event as a "template" for a new one along with a subset of create-sourcing-events parameters.
The following examples assume an understanding of the create-sourcing-events examples. The examples provide JSON data which may be used with the jobs
endpoints as described in Usage.
These examples are specific to the sourcing event from template API, to be used with
the /jobs/create-sourcing-events-from-template endpoint which is fully described
in the OpenAPI Specification.
To begin, a sourcing event identifier is needed to use in the request payload.
Creating a Sourcing Event using a template event
The example below creates a basic Sourcing Event providing a template_sourcing_event_id. The
requested Sourcing Event is relying on the template Sourcing Event to populate all details of the
new sourcing event. The only thing we are required to provide for the new Sourcing Event is a name
and a new schedule.
Basic Example
Template Sourcing Event
For this example, we will be using an existing sourcing event (00000000-0000-0000-0000-000000000000) that has been created with the following specification:
{
"name": "Basic auction event with scheduling for 2023",
"event_type": "AUCTION",
"schedule": [
{
"starts": "2023-01-01T09:00:00Z",
"ends": "2023-01-31T23:59:59Z"
}
],
"bid_sheet": {
"column_roles": { "lot_identifier": "Lot Name" },
"columns": [
{
"name": "Lot Name",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "TEXT"
},
{
"name": "Unit Price",
"column_type": "INPUT",
"input_by": "SUPPLIER_INPUT",
"input_type": "CURRENCY",
"precision": 2
}
],
"lots": [
{
"name": "Lot 1",
"values": [
{ "column": "Lot Name", "value": "Lot 1" }
]
},
{
"name": "Lot 2",
"values": [
{ "column": "Lot Name", "value": "Lot 2" }
]
}
]
},
"primary_cost_calculation": "Unit Price",
"settings": { "is_test": true }
}
Creating a Sourcing Event using a template
An alternative way to create an event is by using an event template. To use a template, provide its ID in the template_id field. Template fields can be overridden by including them in the payload. Similar to using sourcing events as templates, the only required fields for creating a new sourcing event are a name and a schedule.
Basic Example
Template Event
For this example, we will be using a template (11111111-1111-1111-1111-111111111111)
Overwriting fields in the template
In this example we will define a few extra attributes in our payload. We provide the required name and schedule but
also a description, and some bid-sheet lots. The rest of the fields like timezone, bid-sheet columns,
bid-sheet column roles, the primary cost calculation function, and user roles are all populated from the
template Sourcing Event referenced by template_sourcing_event_id or by a template referenced by template_id.
The values defined in the payload will always take precedence over what is in the template Sourcing
Event. For example, the template Sourcing Event defines Lot 1 and Lot 2 in the bid-sheet lots.
Our payload defines Lot 3 and Lot 4. Only Lot 3 and Lot 4 will appear in the Sourcing Event
that is created. If we excluded bid-sheet lots in our request, the values in the template would
be used. The same holds true for all optional fields in the payload.
The roles key in the template enables access to the Sourcing Event for users within your
organisation. All three available role types have been shown in the template: Administrator,
Editor and Viewer. The email addresses provided must be unique and must correspond to existing
Sourcing Optimiser users in your organisation.
Basic Example
Template Sourcing Event
For this example, we will be using an existing sourcing event (00000000-0000-0000-0000-000000000000) that has been created with the following specification:
{
"name": "Basic Event",
"description": "A very simple example event",
"timezone": "Europe/Dublin",
"schedule": [
{
"starts": "2020-01-01T09:00:00Z",
"ends": "2020-01-31T23:59:59Z"
}
],
"bid_sheet": {
"column_roles": { "lot_identifier": "Lot Name" },
"columns": [
{
"name": "Lot Name",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "TEXT"
},
{
"name": "Quantity",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "NUMBER",
"precision": 0
},
{
"name": "Unit Price",
"column_type": "INPUT",
"input_by": "SUPPLIER_INPUT",
"input_type": "CURRENCY",
"precision": 2
}
],
"lots": [
{
"name": "Lot 1",
"values": [
{ "column": "Lot Name", "value": "Lot 1" },
{ "column": "Quantity", "value": "100" }
]
},
{
"name": "Lot 2",
"values": [
{ "column": "Lot Name", "value": "Lot 2" },
{ "column": "Quantity", "value": "200" }
]
}
]
},
"primary_cost_calculation": "Unit Price * Quantity",
"roles": [
{ "email": "administrator@example.buyer.com", "role_type": "ADMIN" },
{ "email": "editor@example.buyer.com", "role_type": "EDITOR" },
{ "email": "viewer@example.buyer.com", "role_type": "VIEWER" }
],
"settings": { "is_test": true }
}
Gotchas
Modifying the template event
When using a Sourcing Event identifier for template_sourcing_event_id, it is important to note that
the details are copied from the original Sourcing Event acting as the template at the time of the request.
If changes are made to the original Sourcing Event acting as the template, they will only be reflected in future Sourcing Events that are created by the API, not any previously created prior to the change.
This could also become an issue if a particular Sourcing Event ís been used as a template for a long period of time, and it is suddenly modified. It might cause the job not to complete successfully.
Template event documents
Attachments on RFI questions on the template event will not currently be copied to the newly created sourcing event. Support for this will be added in the near future.
Events created before 2024 - or copies of these events - which are being used as a template will not have their supporting documents populated on the newly created sourcing event. Supporting documents on template events created in 2024 and beyond will be copied over to the newly created sourcing event.