Positions and seat handovers

A Position is a territory seat: a slot in your field team that owns beats and keeps its own start point, whoever happens to sit in it. A Resource Position record says which executive holds a seat and from when. Together they let you hand a territory from one executive to another by changing one record, instead of editing every beat and every visit plan. You set positions up after your resources and before you attach beats to seats or plan territory by position.

Overview

A seat-owned beat has its Position field set. Plans generated from it go to the seat's current holder, and the beat's own Resource field is kept in step with that holder automatically. When the holder changes, you close their Resource Position record and add one for the new executive. xMatix then moves the seat's beats, and the open future plans on them, to the new holder.

Two records do the work:

The history of a seat is its list of Resource Position records. A record with an empty Effective To is the open one: that executive holds the seat until someone closes it.

When to use it

Use positions when territories outlive the people who work them: staff turnover, transfers between regions, leave cover, or a restructure. If each executive always keeps the same beats, person-owned beats (with only Resource set) are simpler and you don't need positions.

Positions are also used by:

• Plan Territory, which can plan by Positions instead of by resources. Each seat's holder supplies the working hours, and the seat's Operating Location is where the beat starts and ends. See Territory planning.
• Assignment rules, which can hand a record to The current holder of a position.
• The Beats a user can transfer from setting for outlet transfers. A user's own beats include the beats of seats they hold today. See Route stops.

How xMatix handles it

Who holds a seat right now. A Resource Position record holds its seat from its Effective From up to, but not including, its Effective To. An empty Effective From counts as "always", and an empty Effective To as "until further notice". A seat with no record covering the current moment is vacant.

What happens when you save a Resource Position. Saving a new record, changing its Position, Resource, Effective From or Effective To, or deleting it works out each affected seat's holder as of that moment. Then, in the same save:

1. every beat on the seat gets the holder in its Resource field (or an empty Resource if the seat is now vacant);
2. every plan on those beats that is dated today or later, has not been started and is not already settled moves to the holder. A plan that has no assignee, or whose assignee is someone who has held the seat at any time, is moved. A plan that a supervisor gave to someone outside the seat's history is left alone.

If the seat has become vacant, those plans become unassigned.

Dated handovers. A record whose Effective From is in the future doesn't hold the seat yet, so saving it changes nothing at that moment. On its start day, the handover is applied only if the Position-based route assignment (nightly reconcile) setting is on. That job runs once a day and does the same two steps for every seat that owns a beat. With the setting off, beats and already-generated plans stay with the previous holder until a Resource Position on that seat is saved again.

Plan generation. When the generation job creates plans for a seat-owned beat, it assigns each plan to the seat's holder at the time the job runs, whatever date the plan is for. A plan generated for next week therefore goes to today's holder. If the seat changes hands before that date, step 2 above (or the nightly job, for a dated handover) moves it. A beat with a vacant seat still generates its plans, unassigned, so they can be allocated by hand.

The seat's own location. Operating Location is the start and end point for beats planned for the seat. When it is empty, territory planning uses the seat's Branch location instead. Branch is otherwise an administrative grouping and does not decide which beats or outlets the seat has.

What is not acted on. Parent Position is stored and shown, but nothing in xMatix reads it: it does not give a manager's seat any visibility or authority over the seats below it. Manager visibility comes from the role hierarchy and the manager chain. Description is for your notes. Active is read only by assignment rules (an inactive position is never matched). Plan generation, territory planning and the position pickers ignore it.

Prerequisites

• The executives exist as resources.
• You can open the Field Sales Setup app (see Permissions).
• To move beats to seats, you can edit the beats. See Beats and routes.

Procedure

Step 1 — Create a position

1. Open the Field Sales Setup app. Under Territory & Planning, open Positions.
2. Select New.
3. Enter a Name that describes the seat, not the person, for example North Zone Seat 3. Enter a Code if you use one: assignment rules can refer to a position by its code.
4. Pick the Branch the seat belongs to. On a tenant that runs a single company or location, this field may be hidden.
5. If the seat reports to another seat, pick it in Parent Position. This is for reference only.
6. Leave Active ticked.
7. Under Operating Location, place the seat's base on the map: the point where the executive starts and ends the day.
8. Save.

You see the position's record page, with Code and Active in the header. The seat has no holder yet.

Step 2 — Seat an executive

1. In the Field Sales Setup app, open Resource Positions and select New.
2. Pick the Position and the Resource who will hold it. The Resource field is not filled in with your own name; pick the executive.
3. Set Effective From to the first day they hold the seat. If you leave it empty, today's date is used.
4. Leave Effective To empty: this is now the seat's open record.
5. Optionally enter an Assignment Reason, such as New joiner or Transfer.
6. Enter a Name, or leave it empty to get Assignment followed by the date and time of saving.
7. Save.

If the seat already owns beats, they are moved to this executive straight away, with their open plans dated today or later.

Step 3 — Put a beat on the seat

Open the beat and set Position on its Details tab. The beat is now seat-owned, and new plans go to the holder from the next generation run. Setting Position doesn't change the beat's Resource or its existing plans. They follow the holder the next time a Resource Position on that seat is added, changed or deleted, or at the nightly job if the setting is on. For a new seat, it is simplest to put the beats on the seat first and then seat the executive (Step 2).

Existing plans assigned to an executive who has never held the seat count as hand-assigned and are never moved. When you convert a beat to a seat, seat its current executive first, so that their plans move at the first handover. To convert many person-owned beats at once, an administrator can use Assign Positions from Owners; see Beats and routes.

Don't edit Resource by hand on a seat-owned beat. The next save of a Resource Position on that seat, or the nightly job, overwrites it with the holder.

Step 4 — Hand the seat to a new executive

A handover is two saves: close the current record, then add the next one.

1. Open Resource Positions and find the seat's open record (the one with an empty Effective To).
2. Set its Effective To to the handover date, and save. The outgoing executive holds the seat up to that date, but not on it.
3. Select New. Pick the same Position, the incoming Resource, and set Effective From to the same handover date. Enter an Assignment Reason and save.

If the handover date is today, the first save leaves the seat vacant for a moment. The seat's beats lose their Resource and the open plans become unassigned. The second save gives them all to the new holder. Do both steps together.

If the handover date is in the future, nothing moves when you save. The handover is applied on that day only when Position-based route assignment (nightly reconcile) is on (see Configuration). If it is off, do the two saves on the handover day itself instead. Saving a record again without changing the seat, executive or dates doesn't move anything.

Step 5 — Leave a seat vacant or cover it

• Vacancy: close the open record with Effective To and don't add a new one. The seat's beats keep generating plans, unassigned, so a supervisor can allocate them.
• Cover: seat a covering executive as in Step 4, with an Effective To for the end of the cover, then add the returning holder from that date. One executive can hold several seats at the same time.

Step 6 — Review a seat's history

Open Resource Positions. The list shows Name, Position, Resource, Effective From and Effective To. Filter by Position to see everyone who has held a seat, in date order. The position's own record page doesn't list its holders.

Step 7 — Correct or remove a record

Edit a record in place on its record page, or with Edit in the list. Changing the seat, executive or dates runs the same move as a new save. Deleting the open record leaves the seat vacant: its beats lose their Resource and their open future plans become unassigned.

Deleting a Position does not clear it from beats or close its Resource Position records, and those beats keep generating plans for its holder. Before you delete a seat, set a different Position (or clear Position and set Resource) on each of its beats, then close its Resource Position record.

Fields

Position

Resource Position

Business rules

• A Resource Position needs a Position and a Resource, and Effective To must be after Effective From.
• The periods of one seat must not overlap. Ending one record and starting the next on the same date is allowed. An open record (no Effective To) overlaps every later start, so close it before adding the next holder.
• One executive may hold several seats at once. Territory planning by position, though, refuses two selected seats with the same holder.
• Saving, re-dating or deleting a Resource Position immediately sets Resource on the seat's beats to the seat's current holder. It also moves that seat's open plans dated today or later that have not been started. Plans a supervisor gave to someone who never held the seat are not moved.
• Plan generation assigns a seat-owned beat's plans to the holder at the time of generation. A vacant seat produces unassigned plans.
• A future-dated handover takes effect on beats and existing plans on its start day only through the nightly job.
• Assignment rules treat a holder whose Effective To is today as still holding the seat for the whole day. On the handover day, both the outgoing and incoming executive are candidates, and the rule's pick decides.
• Neither record has numbering, a status or an approval.

Example

The North Zone has a seat named North Zone Seat 3, code NZ-03, with its Operating Location at the north depot. Three weekly beats have Position set to this seat. Executive E-1042 has held it since 1 April, on a Resource Position record with no Effective To.

E-1042 transfers to another region from Monday 3 November. Executive E-1187 takes over.

1. On Friday 31 October, the sales manager opens E-1042's open record and sets Effective To to 3 November. Nothing moves yet, because E-1042 still holds the seat today.
2. The manager adds a record for North Zone Seat 3, Resource E-1187, Effective From 3 November, reason Transfer. The save succeeds because the two periods meet but don't overlap.
3. Position-based route assignment (nightly reconcile) is on. On 3 November, the nightly job sets Resource on the three beats to E-1187. It also moves every not-yet-started plan dated 3 November or later, including the plans generated last week for E-1042, to E-1187.
4. One plan that the manager had already given by hand to a third executive for that week stays with that executive.

E-1187 starts from the same depot and visits the same outlets. Nobody edited a beat.

Training

Practice exercise

In a sandbox:

1. Create a position Practice Seat with an Operating Location.
2. Pick a beat owned by resource A that has upcoming plans, and set its Position to Practice Seat.
3. Seat resource A on Practice Seat from today, with no Effective To.
4. Close A's record with Effective To = today, and add resource B from today.

Expected result: after step 3, nothing visible changes: the beat's Resource and its plans are still A's. After step 4, the beat's Resource is B, and its upcoming plans that were not started are assigned to B. Try adding a third record for resource C from yesterday with no Effective To: the save is refused with This seat already has a holder in that period.

Quick reference

• Position = the seat. Resource Position = who holds it, and when.
• The open record has an empty Effective To. A seat has at most one holder at a time.
• Hand over in two saves: close the old record, then add the new one from the same date.
• A same-day handover moves beats and open future plans at once.
• A future-dated handover moves them on the day only if the nightly reconcile setting is on.
• Don't edit Resource on a seat-owned beat; it is overwritten.
• Operating Location is where the seat's beats start and end; Branch is only the fallback.
• Parent Position, Description and Assignment Reason are for reference only.

Permissions

Neither record has its own actions, so record permissions are all that is needed. Because a Resource Position save moves beats and plans, consider removing create, edit and delete on Resource Position from the profile your field executives use. A user without read access to these records doesn't see the lists, and a user without the app doesn't see the Territory & Planning group. See Security profiles.

Configuration

Common problems

"Pick the position (seat) this assignment is for." or "Pick the executive who holds the seat."

A Resource Position needs both a Position and a Resource. Pick the missing one and save again.

"Effective To must be after Effective From."

The end date is on or before the start date. A record that would last zero days isn't allowed. To undo a handover that hasn't started, delete the record instead.

"This seat already has a holder in that period. Close the current assignment (set its Effective To) before adding the next one."

Another record on the same seat covers part of the same period, usually the open record with no Effective To. Set that record's Effective To to the new holder's start date first, then save the new one. Check also for an older closed record whose dates you overlapped.

Plans still go to the previous executive after a handover

• The handover is future-dated and the nightly reconcile setting is off. Turn the setting on; the next nightly run moves the beats and open plans. Re-saving a record without changing it does nothing.
• The plan was already started, is settled, or is dated before today. Those plans are never moved.
• The plan is assigned to someone who never held the seat: a supervisor's hand assignment, or the beat's owner from before it was put on the seat. Reassign it on the Visit Plan.
• The beat has no Position, so it is person-owned. Set Position, or change Resource.

A beat's plans have no assignee

The seat had no holder when the plans were generated or when a Resource Position was last saved. Seat an executive (Step 2). The unassigned plans dated today or later move to them.

Territory planning says "Position(s) without a current holder" or "Two of the selected positions are held by the same executive"

Every seat in a position run needs its own current holder. Seat an executive on each, or leave the seat out. See Territory planning.

An assignment rule that uses a position assigns nobody

The position is inactive, or no record covers today. Tick Active on the position and check its Resource Position records.

Common questions

Does a manager's seat see the beats of the seats below it?

No. Parent Position records the seat structure but nothing reads it, so it gives no visibility, approval or reporting rights. What managers see comes from the role hierarchy and the resources' manager chain. For outlet transfers, the Own and team beats option uses the manager chain, not the seat hierarchy. Keep Parent Position filled in if it helps you read the structure, but don't rely on it for access.

Can one executive hold two seats?

Yes. One executive can have open records on several seats, for example to cover a vacancy, and the plans of all those seats' beats go to them. Only territory planning by position refuses it, because it builds one beat per executive. To plan those seats, give each its own holder first, or plan the covering executive by resource instead.

Why does the beat's Resource change by itself?

On a seat-owned beat, Resource is a copy of the seat's current holder, and xMatix keeps it up to date. It is rewritten whenever a Resource Position on that seat is saved or deleted, and by the nightly job when that setting is on. To give a beat to someone else for good, change the seat's holder. To take it off seat ownership, clear Position and then set Resource.

Is the handover date compared in my local time?

Holder periods are compared against the current time in UTC, and the nightly job runs once per UTC day. A handover dated today, saved during your working day, takes effect at once. A future-dated handover is picked up by the first nightly run on or after its date. For a handover at the start of a working week, saving it the day before is enough.

Related topics

• Beats and routes
• Territory planning
• Visit plans
• Route stops
• Resources
• Position — entity reference
• Resource Position — entity reference