Skip to content

API Walkthroughs 6.1 IPT Singleton move

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

Moves API Walkthrough

6. Inter-Prison Transfer moves (IPTs)

6.1 "Singleton" move for a known person from PrisonA to PrisonB with a range of move dates

  1. [FRONTEND] The initial move record is created in a proposed state with a range of move dates by a PECS PMU user via the frontend. If approved, the move changes to a requested state with a specific move date.

    NB: Whilst not shown in these examples, moves involving children/youths may have documents attached.

    It is not expected that suppliers would create the initial records or approve the move. For the purposes of testing however, 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 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 initial move in proposed state with a range of move dates, using the profile previously just created
curl --request POST \
  --url http://server/api/moves \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: ce0e9608-1291-4ff1-a0d6-02b9ce8ba015' \
  --data '{
    "data": {
      "type": "moves",
      "attributes": {
        "date_from": "2020-07-06",
        "date_to": "2020-07-09",
        "move_agreed": true,
        "move_agreed_by": "Fred Bloggs",
        "status": "proposed",
        "additional_information": "example IPT singleton transfer",
        "move_type": "prison_transfer"
      },
      "relationships": {
        "profile": {
          "data": {
            "type": "profiles",
            "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15"
          }
        },
        "from_location": {
          "data": {
            "type": "locations",
            "id": "067c2855-fa41-493d-9c80-1311a4f7ba45"
          }
        },
        "to_location": {
          "data": {
            "type": "locations",
            "id": "056eed18-772b-45b3-b64a-4d7d563641f7"
          }
        },
        "prison_transfer_reason": {
          "data": {
            "type": "prison_transfer_reasons",
            "id": "1de93692-461f-5355-9e4d-9a0b673daf15"
          }
        }
      }
    }
  }'

  2. [FRONTEND] The proposed move is approved (or rejected) by a PECS Prison user via the front end. If approved, the move changes to a requested state with a specific move date.

    It is not expected that suppliers would approve the move. For the purposes of testing however, frontend requests can be simulated with the following calls:

    curl --request POST \
  --url http://server/api/moves/d5e345ee-4be1-4510-b8ee-7bdf30599711/approve \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: bed1a9dc-8369-492b-b8fe-64e273d05c26' \
  --data '{
 "data": {
  "type": "approve",
  "attributes": {
   "timestamp": "2020-07-16T11:05:23.248Z",
   "date": "2020-07-08"
  }
 }
}'

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

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

    This will return the following JSON:

    {
  "data": [
    {
      "id": "d5e345ee-4be1-4510-b8ee-7bdf30599711",
      "type": "moves",
      "attributes": {
        "additional_information": "example IPT singleton transfer",
        "cancellation_reason": null,
        "cancellation_reason_comment": null,
        "created_at": "2020-07-16T11:44:28+01:00",
        "date": "2020-07-08",
        "date_from": "2020-07-06",
        "date_to": "2020-07-09",
        "move_agreed": true,
        "move_agreed_by": "Fred Bloggs",
        "move_type": "prison_transfer",
        "reference": "AHV9128A",
        "rejection_reason": null,
        "status": "requested",
        "time_due": null,
        "updated_at": "2020-07-16T12:04:51+01:00"
      },
      "relationships": {
        "profile": {
          "data": {
            "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
            "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": {
            "id": "1de93692-461f-5355-9e4d-9a0b673daf15",
            "type": "prison_transfer_reasons"
          }
        },
        "court_hearings": {
          "data": []
        },
        "allocation": {
          "data": null
        },
        "original_move": {
          "data": null
        }
      }
    }
  ],
  "included": [
    {
      "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
      "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": "da8e9326-a417-434a-b67e-66a4e15078d4",
              "type": "profiles"
            },
            {
              "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
              "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": []
        }
      }
    }
  ],
  "links": {
    "self": "http://localhost:5001/api/moves/?filter%5Bdate_from%5D=2020-07-08&filter%5Bdate_to%5D=2020-07-08&filter%5Bstatus%5D=requested&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-08&filter%5Bdate_to%5D=2020-07-08&filter%5Bstatus%5D=requested&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-08&filter%5Bdate_to%5D=2020-07-08&filter%5Bstatus%5D=requested&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": 1,
      "links": {
        "first": "/api/moves?filter%5Bdate_from%5D=2020-07-08&filter%5Bdate_to%5D=2020-07-08&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page=1",
        "last": "/api/moves?filter%5Bdate_from%5D=2020-07-08&filter%5Bdate_to%5D=2020-07-08&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page=1"
      }
    }
  }
}

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

    curl --request POST \
  --url http://server/api/moves/d5e345ee-4be1-4510-b8ee-7bdf30599711/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/vnd.api+json' \
  --header 'idempotency-key: 40154352-4a86-4a5b-bddd-9df63b4d59b4' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-07-07T15:35:24.316Z"
    }
  }
}'

    This will return a 204 No Content response.

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

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

    curl --request POST \
  --url http://server/api/moves/d5e345ee-4be1-4510-b8ee-7bdf30599711/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/vnd.api+json' \
  --header 'idempotency-key: 45a97e52-dc12-4ad5-a47f-fd02e888942c' \
  --data '{
"data": {
  "type": "starts",
  "attributes": {
  "timestamp": "2020-07-07T15:40:46.853Z",
    "notes": "van on the way"
  }
}
}'

    This will return a 204 No Content response.

  7. Optionally, the current move record can be inspected at any time by calling the GET move endpoint, using an ?include parameter as required to return the full person, profile or location records:

    curl --request GET \
  --url 'http://server/api/moves/d5e345ee-4be1-4510-b8ee-7bdf30599711?include=profile.person%2Cfrom_location%2Cto_location' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

    Which returns:

    {
  "data": {
    "id": "d5e345ee-4be1-4510-b8ee-7bdf30599711",
    "type": "moves",
    "attributes": {
      "additional_information": "example IPT singleton transfer",
      "cancellation_reason": null,
      "cancellation_reason_comment": null,
      "created_at": "2020-07-16T11:44:28+01:00",
      "date": "2020-07-08",
      "date_from": "2020-07-06",
      "date_to": "2020-07-09",
      "move_agreed": true,
      "move_agreed_by": "Fred Bloggs",
      "move_type": "prison_transfer",
      "reference": "AHV9128A",
      "rejection_reason": null,
      "status": "requested",
      "time_due": null,
      "updated_at": "2020-07-16T12:04:51+01:00"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
          "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": {
          "id": "1de93692-461f-5355-9e4d-9a0b673daf15",
          "type": "prison_transfer_reasons"
        }
      },
      "court_hearings": {
        "data": []
      },
      "allocation": {
        "data": null
      },
      "original_move": {
        "data": null
      }
    }
  },
  "included": [
    {
      "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
      "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": "da8e9326-a417-434a-b67e-66a4e15078d4",
              "type": "profiles"
            },
            {
              "id": "a631cf66-0ee8-4252-9ef0-408c27ba5c15",
              "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": []
        }
      }
    }
  ]
}

  8. Finally, the move can be completed, changing its status from "in_transit" to “completed” by posting to the complete event endpoint:

    curl --request POST \
  --url http://server/api/moves/d5e345ee-4be1-4510-b8ee-7bdf30599711/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/vnd.api+json' \
  --header 'idempotency-key: 42d19c1f-a741-4fe8-910d-07ffc832aef8' \
  --data '{
"data": {
  "type": "completes",
  "attributes": {
  "timestamp": "2020-07-07T16:19:17.163Z",
    "notes": "move completed successfully"
  }
}
}'

    This will return a 204 No Content response.

Clone this wiki locally