Skip to content

API Walkthroughs 6.2 IPT Allocation move

Jump to bottom
Martyn Whitwell edited this page Jul 24, 2020 · 1 revision

Moves API Walkthrough

6. Inter-Prison Transfer moves (IPTs)

6.2 "Allocation" moves for unknown people from PrisonA to PrisonB on a specific date

  1. [FRONTEND] An initial allocation record and associated move records are created by a PECS PMU user via the frontend. The allocation record is starts in an unfilled state and the move records are in a requested state with a specific move date but without the profile record of the person to be moved.

    It is not expected that suppliers would create the initial allocation/move records or fill them. For the purposes of testing however, frontend requests can be simulated with the following calls:

    # create an allocation for 2 people
curl --request POST \
  --url http://server/api/allocations \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: fe6050e5-ae32-4ed2-b2a7-fe6e3eb2c239' \
  --data '{
  "data": {
    "type": "allocations",
    "attributes": {
      "moves_count": 2,
      "estate": "adult_male",
      "estate_comment": "Another estate description",
      "prisoner_category": "b",
      "sentence_length": "short",
      "other_criteria": "curly hair",
      "requested_by": "Iama Requestor",
      "complete_in_full": true,
      "date": "2020-07-22",
      "complex_cases": [
        {
          "key": "hold_separately",
          "title": "Segregated prisoners",
          "answer": true,
          "allocation_complex_case_id": "8952537a-ecf7-4e25-93d1-2ad67651ad99"
        }
      ]
    },
    "relationships": {
      "from_location": {
        "data": {
          "type": "locations",
          "id": "067c2855-fa41-493d-9c80-1311a4f7ba45"
        }
      },
      "to_location": {
        "data": {
          "type": "locations",
          "id": "056eed18-772b-45b3-b64a-4d7d563641f7"
        }
      }
    }
  }
}'

  2. [FRONTEND] A PECS OCA user fills the allocation by assigning profiles to the move records via the frontend. The allocation changes from an unfilled to a filled state once all moves have been assigned profiles.

    Frontend requests can be simulated with the following calls:

    # find person by prison number
curl --request GET \
  --url 'http://server/api/people?filter%5Bprison_number%5D=G8133UA' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

# create a new profile for person1, synchronised with Nomis alerts
curl --request POST \
  --url http://server/api/people/747f3914-620a-441a-847f-472c79def26c/profiles \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 736916a9-adfc-4442-bb4e-f2c71dbd7b11' \
  --data '{ "data": { "type": "profiles" } }'

# create a new profile for person2, synchronised with Nomis alerts
curl --request POST \
  --url http://server/api/people/fee70079-08c0-4d1c-a125-bfac8caf24c1/profiles \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 73d506c2-da22-48fb-b065-fb525360bec5' \
  --data '{ "data": { "type": "profiles" } }'

# set move1 to profile1
curl --request PATCH \
  --url http://server/api/moves/e9688519-92af-4715-8d88-953846f503ac \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 419b5459-d88e-4e5c-ac14-0dc124ff26e9' \
  --data '{
  "data": {
    "id": "e9688519-92af-4715-8d88-953846f503ac",
    "type": "moves",
    "attributes": {
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "98be8b71-eaf8-4563-bcd0-05af9a80f262"
        }
      }
    }
  }
}'

# set move2 to profile2
curl --request PATCH \
  --url http://server/api/moves/b953e392-87bc-438b-b436-8026e32e5d76 \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: e3f034de-cc14-496b-9ede-47ff6b04a95b' \
  --data '{
  "data": {
    "id": "b953e392-87bc-438b-b436-8026e32e5d76",
    "type": "moves",
    "attributes": {
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "ca23256f-4049-4073-a6fd-c7882c1faa24"
        }
      }
    }
  }
}'

  3. Suppliers can retrieve a list of requested moves for specific dates filtered to allocations by calling the get moves endpoint with appropriate filters:

    curl --request GET \
  --url 'http://server/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

    This will return the following JSON:

    {
  "data": [
    {
      "id": "b953e392-87bc-438b-b436-8026e32e5d76",
      "type": "moves",
      "attributes": {
        "additional_information": null,
        "cancellation_reason": null,
        "cancellation_reason_comment": null,
        "created_at": "2020-07-20T11:09:10+01:00",
        "date": "2020-07-22",
        "date_from": null,
        "date_to": null,
        "move_agreed": null,
        "move_agreed_by": null,
        "move_type": "prison_transfer",
        "reference": "PFR2863M",
        "rejection_reason": null,
        "status": "requested",
        "time_due": null,
        "updated_at": "2020-07-20T11:40:00+01:00"
      },
      "relationships": {
        "profile": {
          "data": {
            "id": "ca23256f-4049-4073-a6fd-c7882c1faa24",
            "type": "profiles"
          }
        },
        "from_location": {
          "data": {
            "id": "067c2855-fa41-493d-9c80-1311a4f7ba45",
            "type": "locations"
          }
        },
        "to_location": {
          "data": {
            "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
            "type": "locations"
          }
        },
        "prison_transfer_reason": {
          "data": null
        },
        "court_hearings": {
          "data": []
        },
        "allocation": {
          "data": {
            "id": "3f99e2df-39bc-4db5-89a6-94ceffbe7661",
            "type": "allocations"
          }
        },
        "original_move": {
          "data": null
        }
      }
    },
    {
      "id": "e9688519-92af-4715-8d88-953846f503ac",
      "type": "moves",
      "attributes": {
        "additional_information": null,
        "cancellation_reason": null,
        "cancellation_reason_comment": null,
        "created_at": "2020-07-20T11:09:10+01:00",
        "date": "2020-07-22",
        "date_from": null,
        "date_to": null,
        "move_agreed": null,
        "move_agreed_by": null,
        "move_type": "prison_transfer",
        "reference": "ETJ2483U",
        "rejection_reason": null,
        "status": "requested",
        "time_due": null,
        "updated_at": "2020-07-20T11:39:16+01:00"
      },
      "relationships": {
        "profile": {
          "data": {
            "id": "98be8b71-eaf8-4563-bcd0-05af9a80f262",
            "type": "profiles"
          }
        },
        "from_location": {
          "data": {
            "id": "067c2855-fa41-493d-9c80-1311a4f7ba45",
            "type": "locations"
          }
        },
        "to_location": {
          "data": {
            "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
            "type": "locations"
          }
        },
        "prison_transfer_reason": {
          "data": null
        },
        "court_hearings": {
          "data": []
        },
        "allocation": {
          "data": {
            "id": "3f99e2df-39bc-4db5-89a6-94ceffbe7661",
            "type": "allocations"
          }
        },
        "original_move": {
          "data": null
        }
      }
    }
  ],
  "included": [
    {
      "id": "ca23256f-4049-4073-a6fd-c7882c1faa24",
      "type": "profiles",
      "attributes": {
        "assessment_answers": [
          {
            "title": "Any other risks",
            "comments": "lAzCdJPxAuYiYJlAzCdJPxAuYiYJ",
            "created_at": "2014-10-17",
            "expires_at": "2015-11-04",
            "assessment_question_id": "4e37ac1a-a461-45a8-bca9-f0e994d3105e",
            "category": "risk",
            "key": "other_risks",
            "nomis_alert_type": "P",
            "nomis_alert_code": "P0",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Nominal",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": null,
            "created_at": "2015-02-22",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "R",
            "nomis_alert_code": "ROM",
            "nomis_alert_type_description": "Risk",
            "nomis_alert_description": "OASys Serious Harm-Medium",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": "HRErJMfhUuLHisGPkEhGRpvHSvjfHHRErJMfhUuLHisGPkEhGRpvHSvjfH",
            "created_at": "2017-02-03",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "P",
            "nomis_alert_code": "PC2",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Cat 2",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-28",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-31",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-10-16",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          }
        ]
      },
      "relationships": {
        "person": {
          "data": {
            "id": "fee70079-08c0-4d1c-a125-bfac8caf24c1",
            "type": "people"
          }
        },
        "documents": {
          "data": []
        }
      }
    },
    {
      "id": "fee70079-08c0-4d1c-a125-bfac8caf24c1",
      "type": "people",
      "attributes": {
        "first_names": "DOMSANIGH",
        "last_name": "CASEDY",
        "date_of_birth": "1995-11-17",
        "gender_additional_information": null,
        "prison_number": "G8133UA",
        "criminal_records_office": "351774/14D",
        "police_national_computer": "14/120018R"
      },
      "relationships": {
        "ethnicity": {
          "data": {
            "id": "a4f988ba-5ebc-4b24-9dfe-b7fa0c23c30e",
            "type": "ethnicities"
          }
        },
        "gender": {
          "data": {
            "id": "ffac6763-26d6-4425-8005-6e5d052aed88",
            "type": "genders"
          }
        },
        "profiles": {
          "data": [
            {
              "id": "5182951e-d121-478a-b61f-79b6afba045f",
              "type": "profiles"
            },
            {
              "id": "379a14d6-96fc-442f-bf21-cc8d649963b1",
              "type": "profiles"
            },
            {
              "id": "ca23256f-4049-4073-a6fd-c7882c1faa24",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "067c2855-fa41-493d-9c80-1311a4f7ba45",
      "type": "locations",
      "attributes": {
        "key": "bsi",
        "title": "BRINSFORD (HMP)",
        "location_type": "prison",
        "nomis_agency_id": "BSI",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    },
    {
      "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
      "type": "locations",
      "attributes": {
        "key": "iwi",
        "title": "ISLE OF WIGHT (HMP)",
        "location_type": "prison",
        "nomis_agency_id": "IWI",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    },
    {
      "id": "98be8b71-eaf8-4563-bcd0-05af9a80f262",
      "type": "profiles",
      "attributes": {
        "assessment_answers": [
          {
            "title": "Any other risks",
            "comments": "lAzCdJPxAuYiYJlAzCdJPxAuYiYJ",
            "created_at": "2014-10-17",
            "expires_at": "2015-11-04",
            "assessment_question_id": "4e37ac1a-a461-45a8-bca9-f0e994d3105e",
            "category": "risk",
            "key": "other_risks",
            "nomis_alert_type": "P",
            "nomis_alert_code": "P0",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Nominal",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": null,
            "created_at": "2015-02-22",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "R",
            "nomis_alert_code": "ROM",
            "nomis_alert_type_description": "Risk",
            "nomis_alert_description": "OASys Serious Harm-Medium",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": "HRErJMfhUuLHisGPkEhGRpvHSvjfHHRErJMfhUuLHisGPkEhGRpvHSvjfH",
            "created_at": "2017-02-03",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "P",
            "nomis_alert_code": "PC2",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Cat 2",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-28",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-31",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-10-16",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          }
        ]
      },
      "relationships": {
        "person": {
          "data": {
            "id": "747f3914-620a-441a-847f-472c79def26c",
            "type": "people"
          }
        },
        "documents": {
          "data": []
        }
      }
    },
    {
      "id": "747f3914-620a-441a-847f-472c79def26c",
      "type": "people",
      "attributes": {
        "first_names": "DOMSANIGH",
        "last_name": "CASEDY",
        "date_of_birth": "1995-11-17",
        "gender_additional_information": null,
        "prison_number": "G8133UA",
        "criminal_records_office": "351774/14D",
        "police_national_computer": "14/120018R"
      },
      "relationships": {
        "ethnicity": {
          "data": {
            "id": "a4f988ba-5ebc-4b24-9dfe-b7fa0c23c30e",
            "type": "ethnicities"
          }
        },
        "gender": {
          "data": {
            "id": "ffac6763-26d6-4425-8005-6e5d052aed88",
            "type": "genders"
          }
        },
        "profiles": {
          "data": [
            {
              "id": "28087623-d310-4a1c-bf17-b992b74e30c2",
              "type": "profiles"
            },
            {
              "id": "f7769f3e-51e3-4b03-91b7-1eb4a79e98f6",
              "type": "profiles"
            },
            {
              "id": "d9a7e87e-b031-4da2-ae13-852aab708aac",
              "type": "profiles"
            },
            {
              "id": "da8e9326-a417-434a-b67e-66a4e15078d4",
              "type": "profiles"
            },
            {
              "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
              "type": "profiles"
            },
            {
              "id": "536068a5-a22e-4c5f-b078-f69c931cd9f1",
              "type": "profiles"
            },
            {
              "id": "98be8b71-eaf8-4563-bcd0-05af9a80f262",
              "type": "profiles"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "per_page": 20,
      "total_pages": 1,
      "total_objects": 2,
      "links": {
        "first": "/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location&page=1",
        "last": "/api/moves?filter%5Bdate_from%5D=2020-07-22&filter%5Bdate_to%5D=2020-07-22&filter%5Bhas_relationship_to_allocation%5D=true&include=profile.person%2Cfrom_location%2Cto_location&page=1"
      }
    }
  }
}

  4. The new moves can then be accepted changing their status from "requested" to “booked” by calling the accept endpoint:

    curl --request POST \
  --url http://server/api/moves/e9688519-92af-4715-8d88-953846f503ac/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: e7b6e6bc-a573-441f-9e3d-e76c15673bd4' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-07-20T10:47:51.589Z"
    }
  }
}'

curl --request POST \
  --url http://server/api/moves/b953e392-87bc-438b-b436-8026e32e5d76/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: b2feae93-fb3d-46e4-93be-8e48908c4308' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-07-20T10:48:03.770Z"
    }
  }
}'

    These calls will return a 204 No Content response.

  5. Journeys should be added to move: please see the separate Journey API walkthrough document.

  6. The moves can be started, changing their status from "booked" to “in_transit” by calling the start endpoint:

    curl --request POST \
  --url http://server/api/moves/e9688519-92af-4715-8d88-953846f503ac/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 648026af-e5af-4ddd-a907-5c252e543e99' \
  --data '{
  "data": {
    "type": "starts",
    "attributes": {
      "timestamp": "2020-07-20T11:01:59.920Z",
      "notes": "van on the way for person1"
    }
  }
}'

curl --request POST \
  --url http://server/api/moves/b953e392-87bc-438b-b436-8026e32e5d76/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 5d489e39-a99a-4fac-b2e1-5321ca688e40' \
  --data '{
  "data": {
    "type": "starts",
    "attributes": {
      "timestamp": "2020-07-20T11:02:26.639Z",
      "notes": "van on the way for person2"
    }
  }
}'

    These calls will return a 204 No Content response.

  7. Finally, the moves can be completed, changing their status from "in_transit" to “completed” by posting to the complete event endpoint:

    curl --request POST \
  --url http://server/api/moves/e9688519-92af-4715-8d88-953846f503ac/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: e5eac82b-4b61-44b6-8144-cff3b524c03c' \
  --data '{
  "data": {
    "type": "completes",
    "attributes": {
      "timestamp": "2020-07-20T11:06:58.724Z",
      "notes": "all is well"
    }
  }
}'

curl --request POST \
  --url http://server/api/moves/b953e392-87bc-438b-b436-8026e32e5d76/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 95485e86-f556-48a4-b2a4-8f96834c1b7f' \
  --data '{
  "data": {
    "type": "completes",
    "attributes": {
      "timestamp": "2020-07-20T11:07:11.132Z",
      "notes": "all is well"
    }
  }
}'

    These calls will return a 204 No Content response.

Clone this wiki locally