Creates a new material mapping for a division.

If material defined in the args does not exist, it is also created.

This endpoint can optionally also add an alias to another material mapping, as sometimes we need to do these two operations together.

If plant compositions are being defined, the cement component materialId for the material being added must be null.

This endpoint can throw one of four custom exceptions depending on user input. All exceptions have an "exceptionType" field (unique identifier for each exception) and an "error" field (short helpful message for developers). Exceptions can have additional fields, documented below.

InvalidFieldValue: Thrown when any specific field fails validation (e.g. specific gravity is negative, mapping cannot be found by a specified ID, etc.). Includes additional field "fieldName" indicating which input failed validation. Sample response:

    {
        "exceptionType": "InvalidFieldValue",
        "error": "Primary material type cannot be updated.",
        "fieldName": "PrimaryMaterialType"
    }

DuplicateMapping: Thrown when a material exactly matches an existing material. Includes additional field "existingMapping" of type MaterialArgs for comparison on the frontend. Sample response:

    {
        "exceptionType": "DuplicateMapping",
        "error": "Mapping already exists.",
        "existingMapping": {
            "materialMappingId": 0,
            "divisionId": 0,
            "divisionName": "string",
            "isIngested": true,
            "primaryMaterialType": "Admixture",
            "materialType": "Cement",
            "specificGravity": 0,
            "supplierCompany": "string",
            "supplierPlant": "string",
            "cementSupplier": {
                "cementPlantId": 0,
                "plantName": "string",
                "companyName": "string"
            },
            ...
        }
    }

SimilarMapping: Thrown when a material's MaterialType and supplier information (plant and company names or cement plant for cements) match an existing material. Similar materials are permitted, so this check can be skipped by setting OverrideSimilarCheck=true in the input args. Includes additional field "existingMapping" of type MaterialArgs for comparison on the frontend. Sample response:

    {
        "exceptionType": "SimilarMapping",
        "error": "Similar material found.",
        "existingMapping": {
            "materialMappingId": 0,
            "divisionId": 0,
            "divisionName": "string",
            "isIngested": true,
            "primaryMaterialType": "Admixture",
            ...
        }
    }

DuplicateAlias: Thrown when an alias is trying to be added to a material but it already exists and is associated with another material mapping. Includes additional field "existingMapping" of type MaterialArgs for comparison on the frontend. Sample response:

    {
        "exceptionType": "DuplicateAlias",
        "error": "Alias already exists.",
        "existingMapping": {
            "materialMappingId": 0,
            "divisionId": 0,
            "divisionName": "string",
            "isIngested": true,
            "primaryMaterialType": "Admixture",
            ...
        }
    }