Producer Management
Producer management refers to a set of features within Socotra designed to support producers such as brokers and agents.
A producer can refer to an individual or an organization, including individuals within an organization. Each producer is associated with one or more producer codes, which can be used to categorize the work performed by a producer. Only one producer can be associated with a given producer code. Each producer can specify a parent producer, forming a producer hierarchy.
Producers and producer codes can contain extension data.
This feature set is under development and will eventually support features such as licensing, appointments, and jurisdictions.
The following functionality is currently supported:
Creating and modifying producers and producer codes via API requests
Modifying producers and producer codes within the Precommit Plugin
Validating producers and producer codes within the Validation Plugin
Lifecycle
The following diagram illustrates the lifecycle for both producers and producer codes:
Producers and producer codes begin in the draft state after creation and will move to the validated state following a successful validation request.
Producers and producer codes can be moved to the suspended state to temporarily prevent them from being used until they are moved back to the validated state following a successful unsuspend request. Once producers and producer codes are moved to the retired or discarded state, they cannot be moved back to the validated state and cannot be used again.
Configuration
Before producers and producer codes can be created, they must be defined within the producerManagement configuration object.
For example:
{
"producerManagement": {
"producers": {
"ExampleProducer": {
"abstract": true,
"extend": "AnotherProducer",
"data": {},
"defaultSearchable": false
}
},
"producerCodes": {
"ExampleProducerCode": {
"abstract": true,
"extend": "AnotherProducerCode",
"numberingPlan": "ExampleNumberingPlan",
"numberingString": "ExampleText",
"data": {},
"defaultSearchable": false
}
}
}
}
Producers and producer codes can be defined as abstract, meaning they cannot be created directly. Producers and producer codes can inherit data from the producer or producer code specified in the extend field.
Producer codes can be automatically generated based on the numberingPlan and numberingString specified in the configuration. We strongly recommend using a separate numbering plan for each producer code type to avoid potential duplication of producer codes. See the Entity Numbering feature guide for more information.
Extension data can be defined in the data field.
The defaultSearchable field can be used to modify search behavior.
Create a Producer
Once your configuration changes have been deployed, create a producer using the Create Producer API endpoint.
For example:
{
"type": "ExampleProducer"
}
The type field refers to the name of a producer defined in the configuration. The parentLocator field can be used to specify a parent producer, forming a producer hierarchy.
For example:
{
"type": "ExampleProducer",
"parentLocator": "01CH383XHA23A"
}
Producer details can be updated by using the Update Producer API endpoint.
Use the Validate Producer API endpoint to validate a producer.
Refer to the Producer Management API index for additional API endpoints.
Create a Producer Code
The Create Producer Code API endpoint can be used to create a producer code.
For example:
{
"type": "ExampleProducerCode",
"code": "9217262"
}
The producerLocator request parameter identifies the producer that will be associated with the producer code. Producer code details can be updated by using the Update Producer Code API endpoint.
The type field refers to the name of a producer code defined in the configuration. The optional code field refers to the producer code. The producer code must be unique. If no producer code is specified, a producer code will be automatically generated based on the numbering plan specified in the configuration for the producer code type.
Use the Validate Producer Code API endpoint to validate a producer code.
Refer to the Producer Management API index for additional API endpoints.
Plugins
Precommit Plugin
The Precommit Plugin can be used to modify the value of a producer or producer code before saving it to the database. See the Precommit Plugin feature guide for more information.
For example:
public class PreCommitPluginImpl implements PreCommitPlugin {
private static final Logger log = LoggerFactory.getLogger(PreCommitPluginImpl.class);
@Override
public AgencyProducer preCommit(AgencyProducerRequest request) {
AgencyProducer producer = request.producer();
return request.producer().toBuilder()
.data(producer.data().toBuilder().email("first.agency@socotra.com").build())
.build();
}
@Override
public SubAgencyProducer preCommit(SubAgencyProducerRequest request) {
SubAgencyProducer producer = request.producer();
return request.producer().toBuilder()
.data(producer.data().toBuilder().email("first.subagency@socotra.com").build())
.build();
}
@Override
public CaliforniaProducerCode preCommit(CaliforniaProducerCodeRequest request) {
CaliforniaProducerCode producerCode = request.producerCode();
return request.producerCode().toBuilder()
.data(producerCode.data().toBuilder().description("added by preCommit").build())
.build();
}
}
Validation Plugin
The Validation Plugin can be used to execute custom validation logic on a producer or producer code. See the Validation Plugin feature guide for more information.
For example:
public class ValidationPluginImpl implements ValidationPlugin {
private static final Logger log = LoggerFactory.getLogger(ValidationPluginImpl.class);
@Override
public ValidationItem validate(AgencyProducerRequest request) {
AgencyProducer producer = request.producer();
if (!producer.data().status().equalsIgnoreCase("active")) {
return ValidationItem.builder()
.locator(producer.locator())
.elementType(producer.type())
.addError("producer must be active")
.build();
}
return ValidationItem.builder().build();
}
@Override
public ValidationItem validate(CaliforniaProducerCodeRequest request) {
CaliforniaProducerCode producerCode = request.producerCode();
if (!producerCode.data().status().equalsIgnoreCase("active")) {
return ValidationItem.builder()
.locator(producerCode.locator())
.elementType(producerCode.type())
.addError("producer code must be active")
.build();
}
return ValidationItem.builder().build();
}
}