Skip to content

API Walkthroughs 9.1 SCH to Court move

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

Moves API Walkthrough

9. Secure Childrens Home (SCH) to Court moves

9.1 Move for a known person from an SCH to a Court with a specific move date

  1. [FRONTEND] The initial move record is created in a requested state with a specific move date by a PECS SCH user via the frontend. A new profile with an uploaded document are assigned to the move.

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

    # find person by police national computer (PNC) number
curl --request GET \
  --url 'http://server/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles' \
  --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: fbc6e69a-1a14-4bff-ad0b-a7445244f12a' \
  --data '{ "data": { "type": "profiles" } }'
  
# upload a document
curl --request POST \
  --url http://server/api/documents \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --header 'idempotency-key: 7a5ac26c-d370-4bbe-9533-208bcde0bf55' \
  --form 'data[attributes][file]=@path/to/the/file/hello_world.txt'
  
# attach the uploaded document to the profile
curl --request PATCH \
  --url http://server/api/people/747f3914-620a-441a-847f-472c79def26c/profiles/9ea0a328-2017-44d0-b43e-5bafc98e48cb \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 6b844797-3b72-49ea-9f2d-f69f74f71bf5' \
  --data '{
  "data": {
    "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
    "type": "profiles",
    "relationships": {
      "documents": {
        "data": [
          {
            "type": "documents",
            "id": "3fcf9777-f40b-4a90-8563-5a9484cff9a2"
          }
        ]
      }
    }
  }
}'

# create move request (Adel Beck SCH to Huddersfield Youth Court) with a specific move date, using the new profile
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: fbd5db30-5f96-4be6-a5c0-45b9d65aca6e' \
  --data '{
  "data": {
    "type": "moves",
    "attributes": {
      "date": "2020-08-03",
      "time_due": "2020-08-03T09:00:00+01:00",
      "status": "requested",
      "additional_information": "example SCH to Court transfer: Adel Beck to Huddersfield",
      "move_type": "court_appearance"
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb"
        }
      },
      "from_location": {
        "data": {
          "type": "locations",
          "id": "5e5da09d-a1b3-46c2-9f62-87c458893c21"
        }
      },
      "to_location": {
        "data": {
          "type": "locations",
          "id": "00034e29-9ef8-4802-a2f5-09342bf9f174"
        }
      }
    }
  }
}'

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

    Note that URLs to documents can be retrieved by including profile.documents as an ?include= parameter. The URL to a document is short-lived (5 minutes) so the document should be retrieved immediately, or the get request re-run later to fetch a new document URL.

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

    This will return the following JSON:

    {
  "data": [
    {
      "id": "42bf728b-0979-402b-9222-4b739f965538",
      "type": "moves",
      "attributes": {
        "additional_information": "example SCH to Court transfer: Adel Beck to Huddersfield",
        "cancellation_reason": null,
        "cancellation_reason_comment": null,
        "created_at": "2020-07-31T09:54:00+01:00",
        "date": "2020-08-03",
        "date_from": null,
        "date_to": null,
        "move_agreed": null,
        "move_agreed_by": null,
        "move_type": "court_appearance",
        "reference": "RJU2934E",
        "rejection_reason": null,
        "status": "requested",
        "time_due": "2020-08-03T09:00:00+01:00",
        "updated_at": "2020-07-31T09:54:00+01:00"
      },
      "relationships": {
        "profile": {
          "data": {
            "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
            "type": "profiles"
          }
        },
        "from_location": {
          "data": {
            "id": "5e5da09d-a1b3-46c2-9f62-87c458893c21",
            "type": "locations"
          }
        },
        "to_location": {
          "data": {
            "id": "00034e29-9ef8-4802-a2f5-09342bf9f174",
            "type": "locations"
          }
        },
        "prison_transfer_reason": {
          "data": null
        },
        "court_hearings": {
          "data": []
        },
        "allocation": {
          "data": null
        },
        "original_move": {
          "data": null
        }
      }
    }
  ],
  "included": [
    {
      "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
      "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": "3fcf9777-f40b-4a90-8563-5a9484cff9a2",
              "type": "documents"
            }
          ]
        },
        "person_escort_record": {
          "data": null
        }
      }
    },
    {
      "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": "1ff724b3-6872-485c-8bfb-15abca5e4865",
              "type": "profiles"
            },
            {
              "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "3fcf9777-f40b-4a90-8563-5a9484cff9a2",
      "type": "documents",
      "attributes": {
        "url": "http://localhost:5001/rails/active_storage/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDRG9JYTJWNVNTSWhNRGs1YW1KbWRYYzViamhzWjJGeWFYVnZkbXg2YTJZeVpHWTJNZ1k2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpVFdGMGRHRmphRzFsYm5RN0lHWnBiR1Z1WVcxbFBTSm9aV3hzYjE5M2IzSnNaQzUwZUhRaU95Qm1hV3hsYm1GdFpTbzlWVlJHTFRnbkoyaGxiR3h2WDNkdmNteGtMblI0ZEFZN0JsUTZFV052Ym5SbGJuUmZkSGx3WlVraUQzUmxlSFF2Y0d4aGFXNEdPd1pVIiwiZXhwIjoiMjAyMC0wNy0zMVQwODo1OTowNloiLCJwdXIiOiJibG9iX2tleSJ9fQ==--027adab2ebc8dab5ed1071386703bf5b3cbbc202/hello_world.txt?content_type=text%2Fplain&disposition=attachment%3B+filename%3D%22hello_world.txt%22%3B+filename%2A%3DUTF-8%27%27hello_world.txt",
        "filename": "hello_world.txt",
        "filesize": 13,
        "content_type": "text/plain"
      }
    },
    {
      "id": "5e5da09d-a1b3-46c2-9f62-87c458893c21",
      "type": "locations",
      "attributes": {
        "key": "sch1",
        "title": "Adel Beck Secure Children's Home",
        "location_type": "secure_childrens_home",
        "nomis_agency_id": "SCH1",
        "can_upload_documents": true,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": [
            {
              "id": "3ef88a47-6f1f-5b9b-b2fc-c0fe42cb0c92",
              "type": "suppliers"
            }
          ]
        }
      }
    },
    {
      "id": "00034e29-9ef8-4802-a2f5-09342bf9f174",
      "type": "locations",
      "attributes": {
        "key": "hudryc",
        "title": "Huddersfield Youth Court",
        "location_type": "court",
        "nomis_agency_id": "HUDRYC",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-08-03&filter%5Bdate_to%5D=2020-08-03&filter%5Bstatus%5D=requested&include=profile.person%2Cprofile.documents%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-08-03&filter%5Bdate_to%5D=2020-08-03&filter%5Bstatus%5D=requested&include=profile.person%2Cprofile.documents%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-08-03&filter%5Bdate_to%5D=2020-08-03&filter%5Bstatus%5D=requested&include=profile.person%2Cprofile.documents%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-08-03&filter%5Bdate_to%5D=2020-08-03&filter%5Bstatus%5D=requested&include=profile.person%2Cprofile.documents%2Cfrom_location%2Cto_location&page=1",
        "last": "/api/moves?filter%5Bdate_from%5D=2020-08-03&filter%5Bdate_to%5D=2020-08-03&filter%5Bstatus%5D=requested&include=profile.person%2Cprofile.documents%2Cfrom_location%2Cto_location&page=1"
      }
    }
  }
}

  3. Download the document - note that although no authoristation is required, the URL is short lived and will time out after 5 minutes

    curl --request --verbose GET \
  --url 'http://server/rails/active_storage/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDRG9JYTJWNVNTSWhNRGs1YW1KbWRYYzViamhzWjJGeWFYVnZkbXg2YTJZeVpHWTJNZ1k2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpVFdGMGRHRmphRzFsYm5RN0lHWnBiR1Z1WVcxbFBTSm9aV3hzYjE5M2IzSnNaQzUwZUhRaU95Qm1hV3hsYm1GdFpTbzlWVlJHTFRnbkoyaGxiR3h2WDNkdmNteGtMblI0ZEFZN0JsUTZFV052Ym5SbGJuUmZkSGx3WlVraUQzUmxlSFF2Y0d4aGFXNEdPd1pVIiwiZXhwIjoiMjAyMC0wNy0zMVQwODo1OTowNloiLCJwdXIiOiJibG9iX2tleSJ9fQ==--027adab2ebc8dab5ed1071386703bf5b3cbbc202/hello_world.txt?content_type=text%2Fplain&disposition=attachment%3B%2Bfilename%3D%22hello_world.txt%22%3B%2Bfilename*%3DUTF-8'\'''\''hello_world.txt'

  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/42bf728b-0979-402b-9222-4b739f965538/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: a2bf3ecd-1d71-4f3e-ba1d-e53084df6d5c' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-07-31T09:23:39.755Z"
    }
  }
}'

    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/42bf728b-0979-402b-9222-4b739f965538/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: e73e94e5-a269-497d-b9de-38dab1368ef1' \
  --data '{
  "data": {
    "type": "starts",
    "attributes": {
      "timestamp": "2020-07-31T09:23:58.115Z",
      "notes": "van on the way"
    }
  }
}'

    This will return a 204 No Content response.

  7. 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/42bf728b-0979-402b-9222-4b739f965538/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 07f9c6bc-eb4d-4521-b8cd-ec08b2cb1522' \
  --data '{
  "data": {
    "type": "completes",
    "attributes": {
      "timestamp": "2020-07-31T09:24:12.516Z",
      "notes": "all is well"
    }
  }
}'

    This will return a 204 No Content response.

Clone this wiki locally