.. _group-reference:

Groups
------

.. warning::
  The following endpoints are only accessible if the organisation
  using the API is Enterprise-enabled. Expect a 403 error (Forbidden) otherwise.


This API allows listing, retrieving, creating, updating and deleting groups.
Groups are identified by their UUID.

**Note:** The entity referred to as ``Group`` in this documentation is known as
``Branch`` in the web application and its supporting documentation.


List Groups
...........

.. http:get:: /group/

   List all groups in the organisation.

   **Sample request**:

   .. sourcecode:: http

      GET /group/?pageSize=3 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   :query sortedBy: can be ordered by ``name``
   :query name: a filtering value for name
   :query archived: a filtering value for archived groups

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json


      {
          "count": 11,
          "items": [
              {
                  "uuid": "4a1de64d6b184abfb5692d2443dfa4d2",
                  "name": "Headquarters",
                  "link": {
                      "url": "https://api.fieldaware.net/group/4a1de64d6b184abfb5692d2443dfa4d2",
                      "rel": "detail"
                  },
                  "archived": false
              },
              {
                  "uuid": "d278b2a84b9a479e912c007bf205f647",
                  "name": "Florida Branch",
                  "link": {
                      "url": "https://api.fieldaware.net/group/d278b2a84b9a479e912c007bf205f647",
                      "rel": "detail"
                  },
                  "archived": false
              },
              {
                  "uuid": "87eb22efd9334268b97ad7d8e0d9b736",
                  "name": "SouthWest Office",
                  "link": {
                      "url": "https://api.fieldaware.net/group/87eb22efd9334268b97ad7d8e0d9b736",
                      "rel": "detail"
                  },
                  "archived": true
              }
          ],
          "page": 0,
          "pageSize": 3,
          "sortedBy": []
      }



Get Group
.........

The group representation includes a list of all users with access to the group.

The level of access granted to the users to specific group data (jobs and users in particular) varies:

* **Base:** the user is based (belongs) to the group. As a result, the user has
  full access to the group's specific data.
* **Full access:** the user, who is not based in this group, has complete access
  to the group's data.
* **View only:** the user, who is not based in this group, has read only access to
  the group specific data.

.. http:get:: /group/(group_ref)

   Retrieve a given group.

   **Sample request**:

   .. sourcecode:: http

      GET /group/4a1de64d6b184abfb5692d2443dfa4d2 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
          "uuid": "4a1de64d6b184abfb5692d2443dfa4d2",
          "name": "Florida Branch",
          "colour": "#00B0FF",
          "location": {
              "streetName": "1600 Euclid Avenue",
              "locality": "South Beach",
              "region": "FL",
              "country": "USA",
              "postcode": "55110"
          },
          "phone": "1-800-1234",
          "archived": false,
          "users: [
              {
                  "access": "base",
                  "uuid": "9f3e7b2251034d0da4c03a7f3a3429d7"
              },
              {
                  "access": "view_only",
                  "uuid": "489b23cd49cb4e158e8379575b271e92"
              },
              {
                  "access": "full_access",
                  "uuid": "30dbe80c1fb044248010aa9d13c22f29"
              }
          ]
      }


Create Group
............

.. http:post:: /group/

   Create a new group.

   **Sample minimal request**: `see below for json field values`

   .. sourcecode:: http

      POST /group/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
          "name": "Test branch",
          "location": {
             "streetName": "123 Fake Street",
             "locality": "Ghost Town"
          }
      }

   **Sample full request**:

   .. sourcecode:: http

      POST /user/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
          "name": "North Carolina Branch",
          "colour": "#00B0FF",
          "phone": "1-800-1234",
          "location": {
              "streetName": "900 Metropolitan Avenue",
              "locality": "Charlotte",
              "region": "NC",
              "country": "USA",
              "postcode": "55110"
          }
      }

   :<json string name: Name given to the group (required)
   :<json location: Address where the group is located (required).
   :<json string colour: Hex color code to be used throughout the system to identify elements belonging to the group. The set of valid values is the following:
    ``#C000FF``, ``#64DD17``, ``#00B0FF``, ``#FFC107``,
    ``#FD29FC``, ``#13E2A7``, ``#FF3D00``, ``#7C4DFF``,
    ``#28E5FD``, ``#02AF96``, ``#F7348C``, ``#488DFC``



   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/group/6e72acbf8c9048d88626cf87e4009ea5

      {
          "uuid": "6e72acbf8c9048d88626cf87e4009ea5",
          "name": "Florida Branch",
          "colour": "#00B0FF",
          "phone": "1-800-1234",
          "location": {
              "country": "USA",
              "region": "FL",
              "postcode": "55110",
              "streetName": "1600 Euclid Avenue",
              "locality": "South Beach"
          }
          "users": [],
          "link": {
              "url": "https://apiqa1.fieldaware.net/group/6e72acbf8c9048d88626cf87e4009ea5",
              "rel": "detail"
          },
          "archived": false
      }


Update Group
............

.. http:put:: /group/(group_ref)

   Update a given group.

   **JSON request body**: Same as `Create Group`_, but with all properties being optional.


Archive/Unarchived Group
........................

.. http:put:: /group/(group_ref)/archive

   Mark a group as archived.

.. http:put:: /group/(group_ref)/unarchive

   Mark a group as not archived.

Neither of these methods require a body in the request.


Delete Group
............

.. http:delete:: /group/(group_ref)

   Delete a given group.