Polling?

[andyws]

Brilliant! HMRC have made some RAML available to 3rd Party Devs ... this has made my day!

Is the interface documented here intended to be a polling interface or do you intend to provide a notification mechanism?

Is this interface intended to provide 'current' views:

• for agents: Who can I can for and in what capacity?
• for clients: Who is acting on my behalf and in what capacity?

Will an agent be able to act on behalf of a client to see which agents can act for the client?

[frankoid]

Hi,

Thanks for getting in touch!

This repository is in a pre-release, in-development state. If you are interested in developing software using this API please can you let us know your contact details (email address, role, company name, optionally phone number) so we can contact you when we're ready to seek feedback.

This API is not intended to provide 'current' views of relationships between agents and customers. Instead, its purpose is to allow relationships to be formed between agents and customers so that HMRC knows that the customer has authorised the agent to view/submit the customer's data. So the domain of this API is invitations to form relationships, not the relationships themselves.

[andyws]

Hi Francis,

I appreciate the pre-release nature of the code. I did sign up on the 23rd Sept at the meeting of HMRC with 3rd party devs to be involved in this work prior to release.

Clearly it is not reasonable for HMRC to 'open source' the dev process and not expect interested parties to express views. Even the state can't have it both ways... ;-)

Wrt the RAML, I do hope that HMRC will provide a current state API to complement the interface currently documented. I feel it would be a significant defect if agents could not determine which clients they hold permissions for and equally for clients to find out which agents are able to act on their behalf and to manage those permissions.

[frankoid]

Hi, there's no problem with interested parties expressing views. We just want to make sure that there's awareness that the APIs documented here are going to change.

[andyws]

Excellent! So can you please take the item below into consideration?

Wrt the RAML, I do hope that HMRC will provide a current state API to complement the interface currently documented. I feel it would be a significant defect if agents could not determine which clients they hold permissions for and equally for clients to find out which agents are able to act on their behalf and to manage those permissions.

[frankoid]

Yes, we will be taking all requests from developers such as yourself into consideration. What are the use cases that you would use the current state API to implement?

[andyws]

Current State Use Cases

Client

1 Client logs onto HMRC site

1.1 Client lists all pending invitations 1.1.1 Client accepts one or more pending invitations 1.1.2 Client rejects one or more pending invitations 1.1.3 Clients amends the period start and end dates agent has requested (All invitations should be time limited) Client proceeds to 1.1.2/3

1.2 Client lists all invitations irrespective of state

1.3 Client lists all agents who have current permissions to act as agent for the Client 1.3.1 Client selects an agent and removes one or more permissions from the agent 1.3.2 Client selects an agent and removes all permissions given to the agent

1.4 Client lists all permissions he could grant to an agent and is provided with a detailed description of each permission

1.5 Client selects the method of notification they require with respect to invitations and any other changes made to their relationship with agents

Client Notes

A client should be notified when an agent sends an invitation

A client should be able to use an agent to act on clients behalf with respect to agent requests. The agent in this case should be able to act as if they were the client with respect to 1.1 - 1.5 above.

A client should be able to logon to an agents site and initiate a request for that agent to act in some capacity for the client

Agent

2 Agent logs onto HMRC site

2.1 Agent lists all pending invitations 2.1.1 Agent cancels invitation 2.1.2 Agent amends invitation which voids previous inviation and sends a new invitation

2.2 Agent is notified of accepted, rejected or expired invitations 2.2.1 Agent is notified when a client amends or removes a permission held by the agent

2.3 Agent sends an invitation including a requested start and end date for the permissions

2.4 Agent lists all clients who have granted permissions to the agent 2.4.1 Agent lists the permissions granted by a client

2.5 Agent lists the services for which HMRC have granted the agent permission to act as an agent 2.5.1 Agent lists all clients who have granted permissions to the agent for a service

2.6 Agent removes some or all of the permission(s) granted by a client to the agent

2.7 Agent requests HMRC grant the agent permission to act as an agent with respect to a service

2.8 Agent removes a service previously granted by HMRC

[frankoid]

Hi Andy,

Thanks for the detailed description. What are the underlying business drivers for this functionality - the "why" to go with the "what"? As an example of what I mean by an "underlying business driver", the underlying business drivers for the invitations functionality are to:

• Allow customers to use agents to help them to interact with HMRC, both to save the customers time and to help the customers be confident that they aren't doing something incorrecty. Out of this comes:
  • allow agents to submit data to HMRC on behalf of their customers
  • allow agents to view their customers data that HMRC holds, so that they can include it in submissions
• Ensure that HMRC meets its confidentiality obligations to its customers (i.e. to not disclose customers' information to third parties without the customers' consent)

Out of those requirements comes a need for customers to authorise their agents to interact with HMRC on the customers' behalf, which is where this invitations API comes in.

The reason I'm asking this is that we are looking to capture the business needs of parties such as yourself and your customers so that we can ensure that the solutions we build meet as many of them as possible. If we simply built requested functionality without understanding the underlying business requirements we'd risk building functionality that doesn't meet the need (due to some detail of the functionality being misunderstood) and we'd lose the opportunity to optimise the number of business requirements being met by considering alternative solutions.

[andyws]

I suspect this is a conversation best conducted around a whiteboard.

That said IMHO the Invitations api as it stands addresses just part of the requirement which is how Agents and Clients can interact through the trusted role of HMRC. The point of the use cases is to draw a bigger picture.